> For the complete documentation index, see [llms.txt](https://docs.xrpl-commons.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xrpl-commons.org/core-dev-bootcamp/module03/appendices/configuration.md).

# Appendix : Configuration Reference

[← Back to SHAMap and NodeStore: Data Persistence and State Management](/core-dev-bootcamp/module03.md)

***

### Introduction

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

## NodeStore Configuration

### `[node_db]` Section

Core database configuration:

```ini
[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)

```ini
[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)

```ini
[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)

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

**In-Memory** (Testing)

```ini
[node_db]
type = Memory
# No path needed
```

### Cache Configuration

```ini
[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:**

```ini
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

```ini
[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

```ini
[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:

```ini
[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:**

```ini
# 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:**

```ini
[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:

```ini
[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

```ini
[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

```ini
[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

```ini
[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

```ini
[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

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

### RPC Configuration for Monitoring

```ini
[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:

```bash
# Validate config file
rippled --validate-cfg

# Expected output:
# Config appears to be valid
```

## Changing Configuration

### Changing Cache Size

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

# Restart rippled
systemctl stop rippled
systemctl start rippled

# Cache takes effect immediately
```

### Changing Backend

```bash
# 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

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
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:**

```bash
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

```ini
[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

```bash
#!/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