Skip to content
Maintained by AxonOps — production-grade documentation from engineers who operate distributed databases at scale

cassandra.yaml Configuration

The cassandra.yaml file is the primary configuration file for Apache Cassandra. It controls cluster identity, network settings, storage paths, performance tuning, security, and operational behavior.

Documentation

Document Description
Parameter Reference Canonical reference of all cassandra.yaml parameters with types, defaults, version compatibility, and brief descriptions
Configuration Guide In-depth explanations, best practices, common mistakes, and production recommendations

File Location

Installation Method Default Path
Package (apt/yum) /etc/cassandra/cassandra.yaml
Tarball $CASSANDRA_HOME/conf/cassandra.yaml
Docker /etc/cassandra/cassandra.yaml
Kubernetes Typically mounted as ConfigMap

Version Compatibility

Parameter Format Changes (Cassandra 4.1+)

Cassandra 4.1 introduced human-readable formats for duration, data size, and data rate parameters.

Format Type Pre-4.1 Example 4.1+ Example
Duration read_request_timeout_in_ms: 5000 read_request_timeout: 5s
Data size commitlog_segment_size_in_mb: 32 commitlog_segment_size: 32MiB
Data rate compaction_throughput_mb_per_sec: 64 compaction_throughput: 64MiB/s

Backward Compatibility

Cassandra 4.1+ accepts both old and new formats. Existing configurations continue to work without modification when upgrading.

See the Parameter Reference for version-specific information on each parameter.

Quick Start

Minimum Required Settings

Before starting a production cluster, these settings must be configured:

# Cluster identity (cannot change after data written)
cluster_name: 'MyCluster'

# Network binding
listen_address: <node_ip>
rpc_address: <node_ip>  # Or 0.0.0.0 with broadcast_rpc_address set

# Seed nodes for cluster discovery
seed_provider:
  - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
      - seeds: "seed1_ip,seed2_ip"

# Topology awareness
endpoint_snitch: GossipingPropertyFileSnitch

Do Not Use Defaults in Production

The default cluster_name: 'Test Cluster' and listen_address: localhost are intended for local development only. Using defaults in production will cause operational issues.

Configuration Categories

Category Key Parameters Reference
Cluster Identity cluster_name, num_tokens, allocate_tokens_for_local_replication_factor Reference
Network listen_address, rpc_address, broadcast_address, ports Reference
Storage data_file_directories, commitlog_directory, hints_directory Reference
Performance concurrent_reads, concurrent_writes, memtable settings Reference
Commit Log commitlog_sync, commitlog_segment_size, commitlog_total_space Reference
Compaction compaction_throughput, concurrent_compactors Reference
Caching key_cache_size, row_cache_size, counter_cache_size Reference
Timeouts read_request_timeout, write_request_timeout, range_request_timeout Reference
Hinted Handoff hinted_handoff_enabled, max_hint_window, hinted_handoff_throttle Reference
Security authenticator, authorizer, encryption options Reference
Gossip seed_provider, endpoint_snitch, phi_convict_threshold Reference