# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xrpl-commons.org/core-dev-bootcamp/module03/appendices/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.