Appendix : Configuration Reference

← Back to SHAMap and NodeStore: Data Persistence and State Management

---

Introduction

Complete reference for NodeStore and SHAMap configuration options in rippled.cfg.

NodeStore Configuration

[node_db] Section

Core database configuration:

[node_db]
type = RocksDB              # Type: RocksDB, NuDB, SQLite, Memory
path = /var/lib/rippled/db  # Database location
cache_size = 256            # Cache size in MB (32-4096 typical)
cache_age = 60              # Cache entry age limit in seconds

Backend Selection

RocksDB (Recommended)

[node_db]
type = RocksDB
path = /var/lib/rippled/db/rocksdb

# RocksDB specific options
compression = true          # Enable compression (reduces disk ~50%)
block_cache_size = 256      # Block cache in MB
write_buffer_size = 64      # Write buffer in MB
max_open_files = 100        # Max concurrent file handles

NuDB (High-Throughput)

[node_db]
type = NuDB
path = /var/lib/rippled/db/nudb

# NuDB specific options
key_size = 32               # SHA256 key size (always 32)
block_size = 4096           # Block size for writes

SQLite (Legacy)

[node_db]
type = SQLite
path = /var/lib/rippled/db/rippled.db

In-Memory (Testing)

[node_db]
type = Memory
# No path needed

Cache Configuration

[node_db]
cache_size = 256            # Size in MB

# Tuning guide:
# Small (32MB):     Minimal memory, slower
# Standard (256MB): Good for most validators
# Large (1GB):      Better sync performance
# Very Large (4GB): Archive nodes

Cache Age:

cache_age = 60              # Seconds before eviction

# Tuning guide:
# Short (30s):      Low memory, frequent eviction
# Standard (60s):   Good balance
# Long (300s):      More memory, longer lifespan

Threading Configuration

[node_db]
async_threads = 4           # Background fetch threads

# Tuning guide:
# Few (2-4):     Lower CPU, simpler
# Standard (4-8): Balance CPU and throughput
# Many (16-32):   High-throughput systems

Batch Operation Configuration

[node_db]
batch_write_size = 256      # Objects per batch

# Note: Most systems don't need to adjust this
# Default of 256 is well-optimized

Online Deletion (Database Rotation)

Enable automatic deletion of old ledgers:

[node_db_rotation]
online_delete = 256         # Keep last N thousand ledgers

# Ledger counts:
# 8 (1 day):   3-5 seconds per ledger
# 256 (8 days): Common for validators
# 1000 (30 days): Archive-ish

Without Rotation:

# Don't set online_delete section
# Database grows unbounded (~1-2 GB per day)
# Eventually disk fills
# Requires manual pruning

Import/Export Configuration

Import from another database:

[node_db]
type = RocksDB
path = /var/lib/rippled/db/new_rocksdb
import_db = /path/to/old/database  # Source database

# During startup, rippled will:
# 1. Open source database
# 2. Read all objects
# 3. Write to destination
# 4. Verify counts match
# 5. Continue with destination as primary

Historical Database Configuration

Keep complete history without deletion:

[node_db]
type = RocksDB
path = /var/lib/rippled/db/rocksdb

# Don't enable online_delete
# Don't set import_db

# Result: Complete ledger history preserved
# Disk grows ~1GB per day initially
# ~500GB - 1TB for ~2 years mainnet

Tuning by Deployment Type

Small Validator

[node_db]
type = RocksDB
path = /var/lib/rippled/db/rocksdb
cache_size = 128            # Limited memory
cache_age = 30              # Short lifespan
async_threads = 2           # Few threads

[node_db_rotation]
online_delete = 256         # Keep 8 days

Expected:

• Memory: ~300MB

• Disk: ~50GB

• CPU: 20-40%

Standard Validator

[node_db]
type = RocksDB
path = /var/lib/rippled/db/rocksdb
cache_size = 256            # Standard size
cache_age = 60              # Standard lifespan
async_threads = 4           # Normal concurrency
compression = true          # Enable compression

[node_db_rotation]
online_delete = 256         # Keep 8 days

Expected:

• Memory: ~500-700MB

• Disk: ~50GB (with rotation)

• CPU: 30-50%

High-Performance Validator

[node_db]
type = NuDB                 # Higher throughput
path = /var/lib/rippled/db/nudb
cache_size = 1024           # Large cache
cache_age = 120             # Longer lifespan
async_threads = 8           # More parallelism
batch_write_size = 512      # Larger batches

[node_db_rotation]
online_delete = 512         # Keep 15 days

Expected:

• Memory: ~1.5GB

• Disk: ~80GB (with rotation)

• CPU: 40-60%

Archive Node

[node_db]
type = RocksDB
path = /var/lib/rippled/db/rocksdb
cache_size = 512            # Medium cache
cache_age = 300             # Long lifespan
async_threads = 16          # Many threads
compression = true          # Important for space

# No online_delete section - keep all history

Expected:

• Memory: ~1GB

• Disk: ~500GB - 1TB

• CPU: 50-70%

Monitoring Configuration

Logging Levels

[logging]
debug                   # Verbose logging
# or
info                    # Standard logging
# or
warning                 # Only warnings and errors

RPC Configuration for Monitoring

[rpc_startup]
command = log_level
severity = debug

# Get metrics via RPC
# rippled-cli server_info | jq '.result.node_db'

Performance Impact Summary

Parameter	Lower Value	Higher Value
cache_size	Less memory, slower	More memory, faster
cache_age	Quick eviction, less memory	Slow eviction, more memory
async_threads	Less CPU, slower I/O	More CPU, faster I/O
compression	Faster disk I/O	Slower disk I/O, less disk space
online_delete	More disk space needed	Smaller database, bounded growth

Configuration Validation

Check configuration syntax:

# Validate config file
rippled --validate-cfg

# Expected output:
# Config appears to be valid

Changing Configuration

Changing Cache Size

# Edit rippled.cfg
nano rippled.cfg
# Change cache_size value

# Restart rippled
systemctl stop rippled
systemctl start rippled

# Cache takes effect immediately

Changing Backend

# This requires data migration

# 1. Stop rippled
systemctl stop rippled

# 2. Export current database
rippled --export current_db export.json

# 3. Update config with new backend
nano rippled.cfg  # Change type = XXX

# 4. Import to new backend
mkdir -p /var/lib/rippled/db/new_backend
rippled --import export.json --ledger-db new_backend

# 5. Backup old database
mv /var/lib/rippled/db/old_backend \
   /var/lib/rippled/db/old_backend.backup

# 6. Restart with new database
systemctl start rippled

# 7. Verify it works
rippled-cli server_info | jq '.result.node_db.type'

Enabling Online Deletion

# Add to rippled.cfg
[node_db_rotation]
online_delete = 256

# Restart rippled
systemctl restart rippled

# Monitor deletion (may take time)
tail -f /var/log/rippled/rippled.log | grep -i delete

Troubleshooting Configuration Issues

Issue: Cache hits too low

Possible causes:

• cache_size too small

• cache_age too short

• High variance in access patterns

Check:

rippled-cli server_info | jq '.result.node_db.cache_hit_rate'

Fix:

• Increase cache_size by 50%

• Increase cache_age to 120

• Verify available memory

Issue: Database corrupted

Possible causes:

• Unclean shutdown

• Disk failure

• Backend corruption

Recovery:

# Stop rippled
systemctl stop rippled

# Backup corrupted database
mv /var/lib/rippled/db /var/lib/rippled/db.corrupt

# Restart (will resync from network)
systemctl start rippled

# Check progress
rippled-cli server_info | jq '.result.ledger.ledger_index'

Issue: Disk space filling

Check:

df -h /var/lib/rippled/

# If near full:
du -sh /var/lib/rippled/db/*

Solution:

• If rotation enabled: wait for deletion to complete

• If rotation disabled: enable it with online_delete = 256

• Monitor with watch -n 1 'du -sh /var/lib/rippled/db'

Issue: Poor write performance

Check:

iostat -x 1 /dev/sda  # Check I/O wait
iotop -o              # Check top I/O processes

Solutions:

• Use SSD (not HDD)

• Enable compression: compression = true

• Switch to NuDB: type = NuDB

• Increase async_threads

Quick Configuration Checklist

[node_db]
type = RocksDB                    # ✓ Choose backend
path = /var/lib/rippled/db        # ✓ Choose location
cache_size = 256                  # ✓ Tune for hardware
cache_age = 60                    # ✓ Default is good
async_threads = 4                 # ✓ Default is good
compression = true                # ✓ Enable (if RocksDB)

[node_db_rotation]
online_delete = 256               # ✓ Prevent unbounded growth

This configuration is production-ready for most validators.

Performance Monitoring Script

#!/bin/bash
# Monitor NodeStore health

while true; do
    clear
    echo "=== NodeStore Health Check ==="

    rippled-cli server_info | jq '{
        "cache_hit_rate": .result.node_db.cache_hit_rate,
        "cache_size_mb": .result.node_db.cache_size,
        "write_latency_us": .result.node_db.write_latency_us,
        "read_latency_us": .result.node_db.read_latency_us,
        "async_queue_depth": .result.node_db.async_queue_depth
    }'

    echo ""
    echo "=== Disk Usage ==="
    du -sh /var/lib/rippled/db/*

    sleep 5
done

---

For more details, see:

• Chapter 6: NodeStore Architecture

• Chapter 8: Cache Layer

• Appendix B: Debugging