Skip to content

Cassandra Configuration Reference

Cassandra configuration is spread across three places: cassandra.yaml for database settings, JVM options files for heap and garbage collection, and OS-level settings for limits and kernel parameters. Changes to some settings take effect immediately; others require a rolling restart.

The defaults prioritize safe startup over performance—Cassandra will run on minimal hardware without crashing, but it will not perform well. Production deployments typically change a dozen or more settings from defaults: larger heap, faster compaction, higher file descriptor limits, and workload-appropriate thread pools.

This reference covers each configuration file and the settings that matter most.

Configuration Files

File Purpose Location
cassandra.yaml Main configuration /etc/cassandra/
cassandra-env.sh Environment variables /etc/cassandra/
jvm.options / jvm11-server.options JVM settings /etc/cassandra/
cassandra-rackdc.properties DC/rack configuration /etc/cassandra/
logback.xml Logging configuration /etc/cassandra/

Documentation Structure

cassandra.yaml

JVM Options

Snitch Configuration

Guardrails

Logging

cassandra.yaml Quick Reference

Essential Settings

# Cluster identification
cluster_name: 'ProductionCluster'
num_tokens: 16

# Network
listen_address: 10.0.0.1
rpc_address: 10.0.0.1
native_transport_port: 9042
storage_port: 7000

# Seeds
seed_provider:
  - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
      - seeds: "10.0.0.1,10.0.0.2"

# Snitch
endpoint_snitch: GossipingPropertyFileSnitch

# Directories
data_file_directories:
  - /var/lib/cassandra/data
commitlog_directory: /var/lib/cassandra/commitlog
saved_caches_directory: /var/lib/cassandra/saved_caches
hints_directory: /var/lib/cassandra/hints

Performance Settings

# Concurrent operations
concurrent_reads: 32
concurrent_writes: 32
concurrent_counter_writes: 32
concurrent_materialized_view_writes: 32

# Compaction
compaction_throughput_mb_per_sec: 64
concurrent_compactors: 2

# Memtable
memtable_heap_space_in_mb: 2048
memtable_offheap_space_in_mb: 2048
memtable_flush_writers: 2

# Commit log
commitlog_sync: periodic
commitlog_sync_period_in_ms: 10000
commitlog_segment_size_in_mb: 32

Timeout Settings

read_request_timeout_in_ms: 5000
write_request_timeout_in_ms: 2000
counter_write_request_timeout_in_ms: 5000
range_request_timeout_in_ms: 10000
truncate_request_timeout_in_ms: 60000
request_timeout_in_ms: 10000

Security Settings

# Authentication
authenticator: PasswordAuthenticator
authorizer: CassandraAuthorizer
role_manager: CassandraRoleManager

# Client encryption
client_encryption_options:
  enabled: true
  optional: false
  keystore: /etc/cassandra/conf/.keystore
  keystore_password: cassandra

# Server encryption
server_encryption_options:
  internode_encryption: all
  keystore: /etc/cassandra/conf/.keystore
  keystore_password: cassandra
  truststore: /etc/cassandra/conf/.truststore
  truststore_password: cassandra

JVM Options Quick Reference

Heap Settings

# jvm11-server.options

# Heap size (set both to same value)
-Xms16G
-Xmx16G

# Or for auto-sizing (not recommended for production)
# -XX:MaxRAMPercentage=50.0

# Use G1GC
-XX:+UseG1GC

# Pause time target
-XX:MaxGCPauseMillis=500

# Other G1 options
-XX:G1RSetUpdatingPauseTimePercent=5
-XX:InitiatingHeapOccupancyPercent=70

# GC Logging
-Xlog:gc*:file=/var/log/cassandra/gc.log:time,uptime:filecount=10,filesize=10M

ZGC Settings (JDK 17+)

# Use ZGC
-XX:+UseZGC
-XX:+ZGenerational

# ZGC options
-XX:SoftMaxHeapSize=28G  # Soft target (under -Xmx)

OS-Level Configuration

sysctl Settings

# /etc/sysctl.d/99-cassandra.conf

# Virtual memory
vm.max_map_count = 1048575
vm.swappiness = 1

# Network
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

Limits

# /etc/security/limits.d/cassandra.conf

cassandra soft memlock unlimited
cassandra hard memlock unlimited
cassandra soft nofile 1048576
cassandra hard nofile 1048576
cassandra soft nproc 32768
cassandra hard nproc 32768

Disable Swap

# Temporary
sudo swapoff -a

# Permanent
# Remove/comment swap entries in /etc/fstab

Disable THP

echo never > /sys/kernel/mm/transparent_hugepage/enabled
echo never > /sys/kernel/mm/transparent_hugepage/defrag

Configuration by Workload

Read-Heavy Workload

# More read threads
concurrent_reads: 64

# Higher key cache
key_cache_size_in_mb: 200

# Leveled compaction (better read performance)
# Set per-table via CQL

# Lower bloom filter FP rate
# Set per-table: bloom_filter_fp_chance = 0.01

Write-Heavy Workload

# More write threads
concurrent_writes: 64

# Larger memtables
memtable_heap_space_in_mb: 4096

# Higher compaction throughput
compaction_throughput_mb_per_sec: 128

# More compaction threads
concurrent_compactors: 4

# Periodic commit log sync
commitlog_sync: periodic
commitlog_sync_period_in_ms: 10000

Time-Series Workload

# Use TWCS per table (via CQL)
# TimeWindowCompactionStrategy with appropriate window

# Set TTL per table
# default_time_to_live

# Lower gc_grace for TTL data
# gc_grace_seconds: 86400  (per table)

# Disable key cache (usually not useful for time-series)
# key_cache_size_in_mb: 0

Configuration Validation

Check Current Config

# Via nodetool
nodetool getlogginglevels
nodetool getstreamthroughput
nodetool getcompactionthroughput

# Via CQL
SELECT * FROM system.local;
SELECT * FROM system_schema.keyspaces;

Common Mistakes

Mistake Correct Approach
Heap > 31GB Keep heap ≤ 31GB (compressed oops)
swap enabled Disable swap completely
listen_address = localhost Use actual IP or 0.0.0.0
Only 1-2 seeds Use 2-3 seeds per DC
THP enabled Disable THP
Low file limits Set to 1M+

Next Steps