Cassandra cassandra.yaml Configuration Guide
This guide explains cassandra.yaml settings in depth: what each setting does, why it might need changing, what can go wrong, and production-tested recommendations.
Quick Reference
For a systematic listing of all parameters with types, defaults, and version information, see the Parameter Reference.
Configuration Impact
Getting configuration wrong can cause data loss, performance problems, or cluster instability. Read the explanations, not just the defaults.
File Location and Basics
Section titled “File Location and Basics”Default locations:- Package install (apt/yum): /etc/cassandra/cassandra.yaml- Tarball install: $CASSANDRA_HOME/conf/cassandra.yaml- Docker: /etc/cassandra/cassandra.yaml- Kubernetes: Usually mounted as ConfigMap
Configuration changes require node restart (except noted).Test changes in non-production first.Version Compatibility
Section titled “Version Compatibility”Parameter Format Changes (Cassandra 4.1+)
Section titled “Parameter Format Changes (Cassandra 4.1+)”Cassandra 4.1 introduced human-readable formats for duration, data size, and data rate parameters. Both old and new formats are supported, but the new format is recommended for clarity.
Duration Parameters
Section titled “Duration Parameters”| Pre-4.1 Format | 4.1+ Format | Example |
|---|---|---|
*_in_ms: 10000 | *: 10s or *: 10000ms | read_request_timeout |
*_in_s: 3600 | *: 1h or *: 3600s | key_cache_save_period |
Duration units: ms (milliseconds), s (seconds), m (minutes), h (hours), d (days)
# Pre-4.1read_request_timeout_in_ms: 5000max_hint_window_in_ms: 10800000
# 4.1+read_request_timeout: 5smax_hint_window: 3hData Size Parameters
Section titled “Data Size Parameters”| Pre-4.1 Format | 4.1+ Format | Example |
|---|---|---|
*_in_kb: 1024 | *: 1024KiB or *: 1MiB | hinted_handoff_throttle |
*_in_mb: 256 | *: 256MiB | commitlog_segment_size |
Data size units: KiB (kibibytes), MiB (mebibytes), GiB (gibibytes)
# Pre-4.1commitlog_segment_size_in_mb: 32hinted_handoff_throttle_in_kb: 1024
# 4.1+commitlog_segment_size: 32MiBhinted_handoff_throttle: 1024KiBData Rate Parameters
Section titled “Data Rate Parameters”| Pre-4.1 Format | 4.1+ Format | Example |
|---|---|---|
*_megabits_per_sec: 200 | *: 200MiB/s | stream_throughput_outbound |
*_mb_per_sec: 64 | *: 64MiB/s | compaction_throughput |
# Pre-4.1compaction_throughput_mb_per_sec: 64stream_throughput_outbound_megabits_per_sec: 200
# 4.1+compaction_throughput: 64MiB/sstream_throughput_outbound: 200MiB/sFormat Compatibility
Cassandra 4.1+ accepts both old and new formats. However, the default cassandra.yaml shipped with each version uses that version's preferred format. When upgrading, existing configurations continue to work without modification.
Key Parameters by Version
Section titled “Key Parameters by Version”| Parameter | 4.0 | 4.1+ |
|---|---|---|
allocate_tokens_for_local_replication_factor | ✅ | ✅ |
| Duration/size format (human-readable) | ❌ | ✅ |
audit_logging_options | ✅ | ✅ |
full_query_logging_options | ✅ | ✅ |
| Guardrails | ✅ (4.1+) | ✅ (expanded) |
Critical Settings (Must Configure Before Production)
Section titled “Critical Settings (Must Configure Before Production)”These settings either cannot be changed after cluster initialization or will cause major problems if left at defaults in production.
cluster_name
Section titled “cluster_name”cluster_name: 'MyProductionCluster'| Aspect | Details |
|---|---|
| Default | 'Test Cluster' |
| Can change | NO - cannot change after writing data |
| Purpose | Identifies cluster; nodes refuse to join mismatched clusters |
| Recommendation | Set meaningful name before first node starts |
What happens if wrong:
- Drivers verify cluster_name on connect; a mismatch causes the connection to be refused
- Cannot rename later without wiping all data
- Cluster with default name screams "test environment"
listen_address / listen_interface
Section titled “listen_address / listen_interface”# Option 1: Specific IPlisten_address: 10.0.0.1
# Option 2: Network interface (Cassandra resolves to IP)listen_interface: eth0
# NEVER use both - pick one| Aspect | Details |
|---|---|
| Default | localhost |
| Can change | Yes, but requires careful coordination |
| Purpose | IP address for inter-node communication |
| Must set | YES - localhost does not work for multi-node |
What happens if wrong:
localhost: Other nodes cannot connect to this node0.0.0.0: INVALID - Cassandra needs specific IP for gossip- Wrong IP: Node unreachable, appears down to cluster
Container/Cloud note:
# In Docker/Kubernetes with dynamic IPs:# Use listen_interface instead of listen_addresslisten_interface: eth0listen_interface_prefer_ipv6: falserpc_address / rpc_interface
Section titled “rpc_address / rpc_interface”# Option 1: Specific IP (clients connect to this)rpc_address: 10.0.0.1
# Option 2: Listen on all interfaces (common in production)rpc_address: 0.0.0.0
# Option 3: Network interfacerpc_interface: eth0| Aspect | Details |
|---|---|
| Default | localhost |
| Can change | Yes, with restart |
| Purpose | IP address for client (CQL) connections |
| Common production | 0.0.0.0 to accept connections on any interface |
What happens if wrong:
localhost: Only local clients can connect- Wrong IP: Clients cannot reach Cassandra
broadcast_address / broadcast_rpc_address
Section titled “broadcast_address / broadcast_rpc_address”# What other nodes see as this node's addressbroadcast_address: 54.123.45.67
# What clients see as this node's addressbroadcast_rpc_address: 54.123.45.67| Aspect | Details |
|---|---|
| Default | Same as listen_address/rpc_address |
| When needed | NAT, cloud environments, containers |
| Purpose | Address advertised to others (vs. address bound locally) |
Cloud/NAT scenario:
# Node's private IP (inside VPC)listen_address: 10.0.0.1
# Node's public IP (what other nodes/clients reach)broadcast_address: 54.123.45.67broadcast_rpc_address: 54.123.45.67
# This tells the cluster:# "I'm listening on 10.0.0.1, but tell everyone to reach me at 54.123.45.67"seed_provider
Section titled “seed_provider”seed_provider: - class_name: org.apache.cassandra.locator.SimpleSeedProvider parameters: - seeds: "10.0.0.1,10.0.0.2,10.0.0.3"| Aspect | Details |
|---|---|
| Purpose | Contact points for new nodes joining cluster |
| Recommendation | 2-3 seeds per datacenter |
| Can change | Yes, with restart |
Seed misconceptions:
WRONG: "Seeds are special leaders"RIGHT: Seeds are just initial contact points for gossip
WRONG: "Make all nodes seeds for redundancy"RIGHT: This breaks gossip protocol, causes performance issues
WRONG: "Seeds handle more traffic"RIGHT: Seeds are only used during startup/rejoining
CORRECT SETUP:- Pick 2-3 stable nodes per DC as seeds- Seeds should be geographically distributed within DC- All nodes must have SAME seed list- Seeds do not need to be first nodes started (but makes it easier)endpoint_snitch
Section titled “endpoint_snitch”endpoint_snitch: GossipingPropertyFileSnitch| Aspect | Details |
|---|---|
| Default | SimpleSnitch |
| Production | GossipingPropertyFileSnitch or cloud-specific |
| Can change | Carefully - requires rolling update |
| Purpose | Determines datacenter and rack for each node |
Snitch options:
| Snitch | Use Case | Requires Additional Config |
|---|---|---|
SimpleSnitch | Dev only, single DC | None |
GossipingPropertyFileSnitch | Production (recommended) | cassandra-rackdc.properties |
Ec2Snitch | AWS single region | None (auto-detect) |
Ec2MultiRegionSnitch | AWS multi-region | broadcast_address required |
GoogleCloudSnitch | GCP | None (auto-detect) |
AzureSnitch | Azure | None (auto-detect) |
GossipingPropertyFileSnitch setup:
# cassandra-rackdc.properties (same directory as cassandra.yaml)dc=us-eastrack=rack1prefer_local=trueWhat happens if wrong:
- Wrong snitch: Replicas placed incorrectly, potential data loss on failure
- Inconsistent DC names: Cassandra sees multiple "DCs," breaks replication
- Changing snitch on running cluster: Data streaming chaos
Network Configuration
Section titled “Network Configuration”# Inter-node communication (must be open between all nodes)storage_port: 7000 # Unencryptedssl_storage_port: 7001 # Encrypted (when internode_encryption enabled)
# Client connectionsnative_transport_port: 9042 # CQLnative_transport_port_ssl: 9142 # CQL over SSL (optional, for separate SSL port)Firewall rules needed:
Between all Cassandra nodes:- TCP 7000 (or 7001 for SSL)- TCP 7199 (JMX - for nodetool)
Between clients and Cassandra:- TCP 9042 (or 9142 for SSL)Native Transport Settings
Section titled “Native Transport Settings”# Enable CQL protocolnative_transport_enabled: true
# Maximum frame size (large batches may need increase)native_transport_max_frame_size_in_mb: 256
# Maximum concurrent connections (per node)native_transport_max_concurrent_connections: -1 # -1 = unlimited
# Maximum concurrent requests per connectionnative_transport_max_concurrent_connections_per_ip: -1Inter-node Compression
Section titled “Inter-node Compression”internode_compression: dc
# Options:# - none: No compression (fastest, most bandwidth)# - dc: Compress only cross-datacenter traffic (recommended for multi-DC)# - all: Compress all inter-node trafficWhen to use what:
none: Single DC with fast network, CPU-constraineddc: Multi-DC with expensive/limited cross-DC bandwidthall: Bandwidth-constrained everywhere
Directory Configuration
Section titled “Directory Configuration”Data Directories
Section titled “Data Directories”data_file_directories: - /var/lib/cassandra/data
# Multiple directories for JBOD (Just a Bunch of Disks):# data_file_directories:# - /mnt/disk1/cassandra/data# - /mnt/disk2/cassandra/data# - /mnt/disk3/cassandra/dataJBOD considerations:
Cassandra places entire SSTables on one diskDistribution is somewhat even, but not perfectIf one disk fills up, writes to tables on that disk failDisk failure loses data on that disk only (replicas on other nodes provide protection)
RAID alternatives:- RAID0: Better throughput, but failure loses all data on node- RAID10: Redundancy, but expensive- JBOD with Cassandra replication: Common, cost-effectiveCommit Log Directory
Section titled “Commit Log Directory”commitlog_directory: /var/lib/cassandra/commitlogCritical: Put commit log on separate physical disk from data if possible.
Why separate disk?- Commit log writes are sequential- Data writes are also sequential (during flush)- On same disk, they compete for I/O- Separate disk: Both get sequential I/O = better throughput
Ideal setup:- Commit log: Fast SSD/NVMe- Data: Can be SSD or NVMe (or spinning disk for capacity)Other Directories
Section titled “Other Directories”# Hints for unavailable nodeshints_directory: /var/lib/cassandra/hints
# Saved caches (key cache, row cache)saved_caches_directory: /var/lib/cassandra/saved_caches
# CDC (Change Data Capture) logscdc_raw_directory: /var/lib/cassandra/cdc_rawDisk Failure Policy
Section titled “Disk Failure Policy”# Response to a filesystem error on a data directorydisk_failure_policy: stop # Default in 5.0, 4.1 and 4.0disk_failure_policy selects what a node does when a data directory raises a filesystem error, and what it does when an SSTable is found to be corrupt. The behaviour is the same in 5.0, 4.1 and 4.0.
| Policy | Filesystem error | Corrupt SSTable | Process |
|---|---|---|---|
die | Terminates the JVM with exit status 100 | Terminates the JVM | Exits without running the drain hook |
stop_paranoid | Stops the native transport and gossip | Stops the native transport and gossip | Keeps running |
stop (default) | Stops the native transport and gossip | Request fails, node keeps serving | Keeps running |
best_effort | Marks the path unwritable, and stops the transports when every disk is full or no writable disk is left for a keyspace | Request fails, node keeps serving | Keeps running |
ignore | Logs the error and lets the request fail | Request fails, node keeps serving | Keeps running |
Under best_effort a node also drops unreadable SSTables from the affected directory after a read error and answers from what remains, so a read at ONE may return obsolete data. A filesystem error raised during startup, before the daemon has finished initialising, terminates the JVM under die, stop_paranoid and stop alike.
What the Stop Policy Does
Section titled “What the Stop Policy Does”Stopping the transports is not a shutdown. The native transport and gossip stop, and the JVM stays up: memtables stay in memory, the commit log sync thread carries on, and JMX stays reachable. The node stops answering CQL and stops participating in gossip. Internode messaging is not stopped, but peers treat the node as down and route around it. The node therefore serves no client traffic while the operating system still sees a healthy process.
Gossip announces the shutdown to live peers before exiting, so peers mark the node down immediately rather than waiting for the failure detector to convict it. Coordinators then store hints for it for up to max_hint_window (3 hours by default), the same as for any other down node.
The affected node reports itself as UN
nodetool status run on a node whose transports have been stopped lists that node as UN, while every other node in the cluster lists it as DN. The failure detector returns alive unconditionally for the local broadcast address, so a node's view of its own state is always up regardless of the actual state; this is unchanged in 5.0, 4.1 and 4.0. Peers act on the shutdown announcement and mark the node down. The peer view is the accurate one. Confirm the local state with nodetool info, which reports Gossip active and Native Transport active.
Confirming the State
Section titled “Confirming the State”# On the affected node: are the transports running?nodetool info | grep -E "Gossip active|Native Transport active"
# From any other node: what do peers see?nodetool status
# The filesystem error is logged before the transports stopgrep -E "Stopping transports|FSError|FSWriteError" /var/log/cassandra/system.logThe log line that precedes the stop names the policy that fired, and the exception above it names the path that failed. Both are needed to tell a failing disk apart from a path that was removed.
Recovery
Section titled “Recovery”Recovery from stop and stop_paranoid is a restart, once the cause of the filesystem error has been dealt with. There is no command that restarts the transports and returns the node to service in the state the policy left it in. A clean stop (systemctl stop, or SIGTERM) runs the drain shutdown hook, which flushes memtables and syncs the commit log. A normal restart therefore loses nothing. Anything the hook did not cover replays from the commit log at start. The die policy removes the shutdown hook before exiting, so commit log replay on the next start is the only recovery path for data still in memtables.
Triggers That Are Not Hardware Faults
Section titled “Triggers That Are Not Hardware Faults”The policy fires on any filesystem error, not only on failing hardware. One case is worth naming because it is an easy mistake: removing a keyspace data directory while a DROP is still in flight. With auto_snapshot enabled (the default), a drop snapshots every table before deleting its SSTables. That is not instantaneous. Over a keyspace with many tables and SSTables it can run for tens of seconds. The statement returns to the client once the schema change is applied, so an rm -rf issued at that point can still execute while a node is working through the directory. Cassandra then fails partway through deleting the table's files, because the directory it is writing in has gone. Since CASSANDRA-15053 (3.0.19, 3.11.5, 4.0) that failure is handled as a filesystem error and routed to disk_failure_policy. Under the default stop, the result is a node with its transports stopped and no hardware fault to find.
On a cluster left at these defaults, reclaiming the space takes a manual step. In 5.0 and 4.1, auto_snapshot_ttl (CASSANDRA-16790) expires drop and truncate snapshots, but it ships commented out with an example of 30d, so nothing expires unless it is set. The setting does not exist in 4.0. By default, on any of the three versions, the snapshots persist until nodetool clearsnapshot removes them.
See disk_failure_policy in the parameter reference for the shipped description of each policy, nodetool info for the transport and gossip flags, and Assess Node Failure for the procedure that establishes what a stopped node has cost and whether a restore is warranted.
Memory and Performance
Section titled “Memory and Performance”Token Allocation
Section titled “Token Allocation”# Number of vnodes per nodenum_tokens: 16
# Automatic token allocation (Cassandra 4.0+)allocate_tokens_for_local_replication_factor: 3| num_tokens | Pros | Cons | Recommendation |
|---|---|---|---|
| 1 | Simple, predictable | Uneven distribution, slow streaming | Legacy only |
| 16 | Good balance | Slight gossip overhead | Recommended (4.0+) |
| 256 | Very even distribution | Memory overhead, slow startup | Legacy default |
Cassandra 4.0+ optimization:
num_tokens: 16allocate_tokens_for_local_replication_factor: 3 # Set to the keyspace replication factor
# This uses a smarter algorithm to distribute tokens evenly# based on expected replication factorConcurrent Operations
Section titled “Concurrent Operations”# Thread pools for different operationsconcurrent_reads: 32concurrent_writes: 32concurrent_counter_writes: 32concurrent_materialized_view_writes: 32Sizing guidelines:
concurrent_reads: 16 × number_of_drives - Reads may block on disk I/O - More threads keep CPU busy while waiting for disk
concurrent_writes: 8 × number_of_CPU_cores - Writes are CPU-bound (serialization, hashing) - Less I/O blocking than reads
Examples:- 4 cores, 1 SSD: reads=16, writes=32- 8 cores, 4 SSDs: reads=64, writes=64- 16 cores, 8 NVMe: reads=128, writes=128Memtable Configuration
Section titled “Memtable Configuration”# Memory for memtables (on-heap)memtable_heap_space_in_mb: 2048
# Memory for memtables (off-heap, reduces GC pressure)memtable_offheap_space_in_mb: 2048
# How memtable memory is allocatedmemtable_allocation_type: heap_buffers# Options: heap_buffers, offheap_buffers, offheap_objects
# Number of concurrent memtable flushesmemtable_flush_writers: 2
# When to start flushing (fraction of total memtable space)memtable_cleanup_threshold: 0.11Memory math:
Total memtable space = memtable_heap_space + memtable_offheap_space
When total memtables reach (memtable_cleanup_threshold × heap_size): Cassandra flushes the largest memtable
Example with 8GB heap: memtable_cleanup_threshold: 0.11 Flush trigger: 8GB × 0.11 = 880MB in memtables
For large heaps (>16GB), consider: memtable_allocation_type: offheap_buffers This moves memtable data off JVM heap → less GC pressureCommit Log Configuration
Section titled “Commit Log Configuration”Sync Mode
Section titled “Sync Mode”# How commit log is synced to diskcommitlog_sync: periodiccommitlog_sync_period: 10s # 4.1+ format# commitlog_sync_period_in_ms: 10000 # Pre-4.1 format
# Alternative: batch mode, which fsyncs on each write and has no window# commitlog_sync: batch
# Alternative: group mode, where one fsync covers a window of writes# commitlog_sync: group# commitlog_sync_group_window: 1000ms # 4.1+ format, shipped example value# commitlog_sync_group_window_in_ms: 1000 # Pre-4.1 formatTrade-off: Periodic acknowledges a write before it is synced, so it is the only mode with a window to lose; that window runs until writers block, which happens once the sync thread falls behind by more than periodic_commitlog_sync_lag_block, or 1.5 sync periods by default. Group and batch acknowledge only after the fsync, so their durability is identical and only latency differs.
| Mode | Latency | Throughput | Data Loss Risk |
|---|---|---|---|
periodic (10s) | No fsync wait | Highest | Up to 15 seconds |
periodic (1s) | No fsync wait | High | Up to 1.5 seconds |
group | Up to the window, plus one fsync | Medium | None once acknowledged |
batch | One fsync per write | Lowest | None once acknowledged |
Why periodic is usually fine:- Data is on multiple replicas (RF=3)- For data loss: ALL replicas must fail within sync period- Very unlikely scenario
When to use batch:- Regulatory requirements for durability- Single replica or RF=1- Financial/banking applicationsCommit Log Sizing
Section titled “Commit Log Sizing”# Size of each segment filecommitlog_segment_size: 32MiB # 4.1+ format# commitlog_segment_size_in_mb: 32 # Pre-4.1 format
# Total space for all commit logscommitlog_total_space: 8192MiB # 4.1+ format# commitlog_total_space_in_mb: 8192 # Pre-4.1 formatWhat happens when commit log fills up:
If commitlog_total_space reached:1. Writes BLOCK (cannot accept new writes)2. Cassandra forces memtable flush3. Flushed memtables allow commit log segments to be recycled4. Writes resume
Symptoms:- Sudden write latency spike- "Commit log segment limit reached" in logs
Prevention:- Size appropriately for write rate- Monitor commit log segment count- Ensure memtables flush regularlyCompaction Configuration
Section titled “Compaction Configuration”Throughput Throttling
Section titled “Throughput Throttling”# Maximum compaction throughputcompaction_throughput: 64MiB/s # 4.1+ format# compaction_throughput_mb_per_sec: 64 # Pre-4.1 format
# Set to 0 for unlimited (careful!)Tuning compaction throughput:
Low value (32-64):- Protects read/write latency- Compaction may fall behind on write-heavy workloads
High value (128-256):- Compaction keeps up with writes- May impact read/write latency during compaction
Unlimited (0):- Compaction runs as fast as possible- Risk of overwhelming disk I/O- Only use if compaction consistently behind# Change at runtime (does not persist)nodetool setcompactionthroughput 128Concurrent Compactors
Section titled “Concurrent Compactors”concurrent_compactors: 2
# Default: min(8, number of disks, number of cores)Guidelines:
Single SSD: 1-2 compactorsMultiple SSDs (JBOD): Number of disks, up to 4NVMe: 2-4 depending on cores
Too many compactors:- I/O contention between compactions- Impact on read/write latency
Too few compactors:- Compaction backlog- SSTable count grows- Read latency increasesLarge Partition Handling
Section titled “Large Partition Handling”# Warn in log when partition exceeds this size during compactioncompaction_large_partition_warning_threshold_mb: 100Large partitions cause:
- Compaction memory pressure
- Read timeouts (entire partition loaded for range queries)
- Heap pressure during repair
Timeout Configuration
Section titled “Timeout Configuration”Read/Write Timeouts
Section titled “Read/Write Timeouts”# 4.1+ format (duration)read_request_timeout: 5swrite_request_timeout: 2srange_request_timeout: 10scounter_write_request_timeout: 5scas_contention_timeout: 1srequest_timeout: 10s
# Pre-4.1 format (milliseconds)# read_request_timeout_in_ms: 5000# write_request_timeout_in_ms: 2000# range_request_timeout_in_ms: 10000# counter_write_request_timeout_in_ms: 5000# cas_contention_timeout_in_ms: 1000# request_timeout_in_ms: 10000Timeout strategy:
Writes should timeout before reads (prevent zombie writes): write_request_timeout < read_request_timeout
Counter writes need more time (read + write): counter_write_timeout ≥ read_timeout + write_timeout
Range scans need most time: range_request_timeout > read_request_timeout
LWT has inherent latency: cas_contention_timeout should accommodate 4 round tripsWhen to increase timeouts:
Cross-datacenter operations: Higher latency - Increase for QUORUM (cross-DC) operations - Keep lower for LOCAL_* operations
Large partitions: Slower reads - Temporary fix: increase timeout - Real fix: redesign data model
Under load: Higher contention - Temporary: increase timeout - Real fix: scale cluster or optimize queriesCaching Configuration
Section titled “Caching Configuration”Key Cache
Section titled “Key Cache”# Size (caches partition key → SSTable offset)key_cache_size: 100MiB # 4.1+ format# key_cache_size_in_mb: 100 # Pre-4.1 format
# How often to save to diskkey_cache_save_period: 4h # 4.1+ format# key_cache_save_period: 14400 # Pre-4.1 (seconds)
# Number of keys to savekey_cache_keys_to_save: 100000Key cache explained:
What it caches: Partition key → byte offset in SSTable index
Benefits: Avoids reading SSTable index from disk Very memory-efficient (~8 bytes per key)
Sizing: Default: min(5% heap, 100MB) Monitor hit rate via JMX Increase if hit rate low and memory availableRow Cache (Use With Caution)
Section titled “Row Cache (Use With Caution)”# Size (caches entire rows)row_cache_size: 0MiB # 4.1+ format (disabled by default)# row_cache_size_in_mb: 0 # Pre-4.1 format
# How often to saverow_cache_save_period: 0s # 4.1+ format# row_cache_save_period: 0 # Pre-4.1 (seconds)Row cache: Usually a bad idea:
Sounds good: "Cache entire rows in memory!"
Reality:- Uses significant heap (entire rows, not just keys)- GC pressure from large objects- Invalidation on any write- Often less effective than OS page cache
When it might help:- Very small table (< 1GB)- Extremely read-heavy (99.9% reads)- Rows rarely change- Consistent hot set (same rows read repeatedly)
Better alternative: Let OS page cache handle itSecurity Configuration
Section titled “Security Configuration”Authentication
Section titled “Authentication”# No authentication (default, NOT for production)authenticator: AllowAllAuthenticator
# Username/password authenticationauthenticator: PasswordAuthenticatorEnabling authentication:
# Step 1: Set authenticatorauthenticator: PasswordAuthenticator
# Step 2: Restart node
# Step 3: Connect with default credentials# cqlsh -u cassandra -p cassandra
# Step 4: Change default password immediately!ALTER USER cassandra WITH PASSWORD 'new_secure_password';
# Step 5: Create application usersCREATE ROLE app_user WITH PASSWORD = 'app_password' AND LOGIN = true;Authorization
Section titled “Authorization”# No authorization (default)authorizer: AllowAllAuthorizer
# Role-based access controlauthorizer: CassandraAuthorizer
# Required for CassandraAuthorizerrole_manager: CassandraRoleManagerEnabling authorization:
-- After enabling CassandraAuthorizer and restarting
-- Grant permissionsGRANT SELECT ON KEYSPACE my_app TO app_read_user;GRANT MODIFY ON KEYSPACE my_app TO app_write_user;GRANT ALL ON KEYSPACE my_app TO app_admin;
-- Role hierarchyCREATE ROLE developers;GRANT SELECT ON KEYSPACE my_app TO developers;GRANT developers TO dev_user1;GRANT developers TO dev_user2;Encryption: Client-to-Node
Section titled “Encryption: Client-to-Node”client_encryption_options: enabled: true optional: false # true = allow unencrypted connections too keystore: /etc/cassandra/ssl/.keystore keystore_password: ${KEYSTORE_PASSWORD} # Environment variable truststore: /etc/cassandra/ssl/.truststore truststore_password: ${TRUSTSTORE_PASSWORD} protocol: TLS accepted_protocols: - TLSv1.2 - TLSv1.3 cipher_suites: - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 require_client_auth: false # true = mutual TLSEncryption: Node-to-Node
Section titled “Encryption: Node-to-Node”server_encryption_options: internode_encryption: all # Options: none, dc (only cross-DC), rack (only cross-rack), all keystore: /etc/cassandra/ssl/.keystore keystore_password: ${KEYSTORE_PASSWORD} truststore: /etc/cassandra/ssl/.truststore truststore_password: ${TRUSTSTORE_PASSWORD} require_client_auth: true # Recommended: nodes must authenticate require_endpoint_verification: true # Verify hostnameHinted Handoff
Section titled “Hinted Handoff”# Enable/disable hintshinted_handoff_enabled: true
# Maximum time to store hints for unavailable nodemax_hint_window: 3h # 4.1+ format# max_hint_window_in_ms: 10800000 # Pre-4.1 format
# Throttle hint delivery per destinationhinted_handoff_throttle: 1024KiB # 4.1+ format# hinted_handoff_throttle_in_kb: 1024 # Pre-4.1 format
# Maximum hints stored per destination hostmax_hints_file_size: 128MiB # 4.1+ format# max_hints_file_size_in_mb: 128 # Pre-4.1 formatHint configuration strategy:
max_hint_window_in_ms: - Longer = more hints stored = more recovery possible - Shorter = less disk used = faster recovery - Default 3 hours handles most temporary outages - For planned maintenance exceeding 3 hours: run repair after
hinted_handoff_throttle_in_kb: - Protects recovering node from being overwhelmed - Increase if node recovery is slow - Decrease if recovering node CPU/disk constrained
When hints matter: - Node temporarily down (network, restart, etc.) - Hints replay when node returns - If down longer than max_hint_window: hints dropped, need repairGossip and Failure Detection
Section titled “Gossip and Failure Detection”# How often to gossip (milliseconds)# Do not change unless the gossip protocol is well understood# gossip_settle_min_wait_ms: 5000
# Failure detection thresholdsphi_convict_threshold: 8# Higher = more tolerant of latency spikes# Lower = faster failure detection# Default 8 is good for most deploymentsPhi convict threshold tuning:
Cloud environments with variable latency: phi_convict_threshold: 12
Very stable, low-latency network: phi_convict_threshold: 6
Symptoms of too low: - Nodes flapping (marking down/up frequently) - "Marking X as DOWN" followed by "Marking X as UP" in logs
Symptoms of too high: - Slow failure detection - Long time before traffic routes around failed nodeTombstone Protection
Section titled “Tombstone Protection”# Warn when query scans this many tombstonestombstone_warn_threshold: 1000
# Fail query when this many tombstones scannedtombstone_failure_threshold: 100000Tombstone thresholds explained:
What triggers these: - Wide partition with many deletes - Range query over deleted data - Poor data model (delete pattern does not match read pattern)
Warning (1000): - Logged in system.log - Query still completes - Investigate data model
Failure (100000): - Query aborted - Client gets TombstoneOverwhelmingException - Immediate attention needed
Fixes: 1. Fix data model (avoid wide partitions with deletes) 2. Run major compaction (temporary fix) 3. Increase thresholds (hides problem, not recommended)Production Configurations
Section titled “Production Configurations”Minimal Single-DC Production
Section titled “Minimal Single-DC Production”cluster_name: 'Production'num_tokens: 16allocate_tokens_for_local_replication_factor: 3
seed_provider: - class_name: org.apache.cassandra.locator.SimpleSeedProvider parameters: - seeds: "10.0.0.1,10.0.0.2"
listen_address: ${NODE_IP}rpc_address: 0.0.0.0broadcast_rpc_address: ${NODE_IP}
endpoint_snitch: GossipingPropertyFileSnitch
data_file_directories: - /var/lib/cassandra/datacommitlog_directory: /var/lib/cassandra/commitloghints_directory: /var/lib/cassandra/hints
authenticator: PasswordAuthenticatorauthorizer: CassandraAuthorizerrole_manager: CassandraRoleManager
concurrent_reads: 32concurrent_writes: 32
commitlog_sync: periodiccommitlog_sync_period_in_ms: 10000Multi-DC Production
Section titled “Multi-DC Production”cluster_name: 'GlobalProduction'num_tokens: 16allocate_tokens_for_local_replication_factor: 3
seed_provider: - class_name: org.apache.cassandra.locator.SimpleSeedProvider parameters: # 2 seeds from each DC - seeds: "10.0.0.1,10.0.0.2,10.1.0.1,10.1.0.2"
listen_address: ${PRIVATE_IP}broadcast_address: ${PUBLIC_IP}rpc_address: 0.0.0.0broadcast_rpc_address: ${PUBLIC_IP}
endpoint_snitch: GossipingPropertyFileSnitch
internode_compression: dc
server_encryption_options: internode_encryption: all keystore: /etc/cassandra/ssl/.keystore keystore_password: ${KEYSTORE_PASSWORD} truststore: /etc/cassandra/ssl/.truststore truststore_password: ${TRUSTSTORE_PASSWORD} require_client_auth: true
client_encryption_options: enabled: true keystore: /etc/cassandra/ssl/.keystore keystore_password: ${KEYSTORE_PASSWORD}
authenticator: PasswordAuthenticatorauthorizer: CassandraAuthorizerHigh-Throughput Write-Heavy
Section titled “High-Throughput Write-Heavy”# Larger memtables = fewer flushesmemtable_heap_space_in_mb: 4096memtable_offheap_space_in_mb: 4096memtable_flush_writers: 4
# More concurrent writesconcurrent_writes: 64
# Higher compaction throughputcompaction_throughput_mb_per_sec: 128concurrent_compactors: 4
# Larger commit logcommitlog_total_space_in_mb: 16384Common Misconfigurations
Section titled “Common Misconfigurations”| Mistake | Symptom | Fix |
|---|---|---|
listen_address: localhost | Nodes cannot gossip | Use actual IP |
seed_provider: all nodes | Gossip protocol breaks | 2-3 seeds per DC |
row_cache_size_in_mb: 1000 | GC pauses, heap pressure | Set to 0 |
concurrent_compactors: 16 | I/O contention, slow reads | Match disk count |
Different cluster_name | Node will not join | Must match all nodes |
| Wrong snitch | Replica placement wrong | Match topology |
Next Steps
Section titled “Next Steps”- JVM Tuning - Heap sizing and garbage collector settings per version
- JVM Options - Which options file holds which settings
- Snitch Configuration - Detailed topology setup
- Security - Authentication and encryption
- Performance Tuning - Optimization strategies
- Operations - Day-to-day management