XRPLF/rippled master · Sections.h · xrpl.org docs.
Defaults marked src? require verification in C++ source.
Parameters for rippled.cfg.
All section and key names sourced from src/xrpld/core/Sections.h.
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [node_size] | auto (medium) | tiny | small | medium | large | huge | Master tuning knob. Sets cache sizes, object limits, thread allocations. Auto-detects from RAM on startup. BUG Auto collapses large→medium on 4-core/32GB. Docs now explicitly say large is not recommended — use huge if ≥32GB. | |
| [workers] | CPU cores + 2 | integer ≥ 1 | App worker threads for peer/client request processing. Standalone mode defaults to 1. Interaction with node_size needs source verification in Config.cpp. | |
| [io_workers] | src? hardcoded pre-PR#3994 | integer | Raw inbound/outbound IO threads. Hub operators should increase. Default not documented — read Config.cpp. | |
| [prefetch_workers] | src? | integer | Threads for nodestore prefetching. Tuning this improves ledger fetch performance under load. | |
| [sweep_interval] | src? | integer (seconds) | Frequency of cache sweep to evict stale objects. Lower = faster memory release, higher CPU cost. | |
| [max_transactions] | 250 | 100 – 1000 | Max transactions in job queue before throttling. Hard floor 100, ceiling 1000. |
| Key | Default | Valid Values | Description | |
|---|---|---|---|---|
| type | NuDB | NuDB | RocksDB | Database backend. NuDB has near-constant performance regardless of data size. RocksDB is legacy — avoid for new deployments. | |
| path | (required) | directory path | Ledger store location on disk. High-grade SSD required. >10,000 reads/sec and >7,000 writes/sec observed on production clusters. | |
| online_delete | 2000 | integer (ledger count) | How many ledger versions to retain (2000 ≈ 2 hours). Must be ≥ ledger_history. Full history servers omit this. Plan for 2× this value in disk space. | |
| advisory_delete | 0 | 0 | 1 | 0 = auto-delete on threshold. 1 = wait for can_delete RPC before deleting. Useful for maintenance windows. | |
| cache_mb | src? | integer (MB) | RocksDB Cache size in MB. BUG2 Investigate whether node_size scales this proportionally — if not, large underperforms medium. | |
| cache_size | 16384 | integer (records) | NuDB cache record count. 0 = use default. | |
| cache_age | src? | integer (minutes) | How long to keep DB records in cache. | |
| bg_threads | src? | integer | RocksDB Background compaction threads. BUG2 If node_size sets cache_mb but not bg_threads proportionally, large underperforms medium. | |
| open_files | 512 | integer | RocksDB Open file handles. | |
| filter_bits | 12 | integer | RocksDB Bloom filter bits per key. | |
| file_size_mb | 64 | integer | RocksDB SST file target size in MB. | |
| file_size_mult | 2 | integer | RocksDB File size level multiplier. | |
| earliest_seq | 32570 | integer ≥ 1 | Earliest ledger sequence to store. Override to 1 for private networks starting from genesis. | |
| nudb_block_size | src? | integer | NuDB Block size tuning parameter. |
| Section / Key | Default | Valid Values | Description | |
|---|---|---|---|---|
| [database_path] | (required) | directory path | Where SQLite bookkeeping DBs are stored: transaction data, amendment votes, peer reservations. Separate from node_db. | |
| journal_mode | src? | WAL | DELETE | TRUNCATE | SQLite journal mode. WAL recommended for best performance. | |
| journal_size_limit | src? | integer (bytes) | SQLite WAL file size before forcing a checkpoint. | |
| synchronous | src? | NORMAL | FULL | OFF | SQLite sync mode. FULL = safest, NORMAL = faster. | |
| temp_store | src? | 0 | 1 | 2 | SQLite temp storage: 0=default, 1=file, 2=memory. | |
| page_size | src? | integer | SQLite page size in bytes. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [ips] | r.ripple.com 51235 + 3 others | hostname/IP list | Bootstrap peer list. One per line, optional port. Default hardcoded in source. Validators should override with ips_fixed peers only. | |
| [ips_fixed] | empty | hostname:port list | Persistent connections never dropped by churn. Use for validator→hub links. Port required. | |
| [peer_private] | 0 | 0 | 1 | 1 = hide your IP from being advertised to the network. Validators should always use 1. Must have ips_fixed set if enabled. | |
| [peers_max] | src? | integer | Total max peer connections (in + out). Cluster/fixed peers excluded from count. Implementation-enforced minimum. | |
| [peers_in_max] | src? | integer | Max inbound peers independently. Added v1.7.0. | |
| [peers_out_max] | src? | integer | Max outbound peers independently. Added v1.7.0. | |
| [network_id] | not set | 0=main | 1=testnet | 2=devnet | uint32 | Prevents accidental cross-network peering. Server refuses connections from nodes on a different network_id. | |
| [network_quorum] | src? | integer | Min peer count before node starts processing ledgers. | |
| [compression] | false | true | false | LZ4 peer message compression. Both peers must have it enabled. Saves bandwidth, costs CPU. | |
| [reduce_relay] | src? | 0 | 1 | Reduces redundant message relay between peers. | |
| [cluster_nodes] | empty | pubkey [name] list | rippled-level cluster: full trust between listed nodes. Only for co-administered servers. | |
| [elb_support] | src? | 0 | 1 | AWS ELB/load balancer proxy protocol. Passes real client IP. | |
| [server_domain] | empty | domain string | Published in crawl data. Domain TOML should reference this node's pubkey. | |
| [overlay] public_ip | src? | IPv4 address | Known fixed public IP. Helps peers connect correctly when behind NAT. | |
| [overlay] vp_enable | src? | 0 | 1 | Validator propagation squelch. Reduces redundant validation message relay. | |
| [overlay] tx_relay_percentage | src? | integer % | Percentage of peers to relay transactions to when reduce_relay is active. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [ledger_history] | 256 | integer | full | none | Ledger versions to back-fill and keep. Must be ≤ node_db online_delete. 256 is sufficient for consensus. Full history ≈ 26TB. | |
| [fetch_depth] | src? | integer | full | How far back to serve ledger history to requesting peers. | |
| [ledger_replay] | 0 (disabled) | 0 | 1 | Experimental. Acquires ledgers by replaying transactions rather than downloading state snapshots. Not for production. | |
| [ledger_tx_tables] | src? | 0 | 1 | Whether ledger/transaction lookup tables are maintained in the SQLite DB. |
| Key | Default | Valid Values | Description | |
|---|---|---|---|---|
| ledgers_in_queue | src? | integer | Ledgers worth of transactions to hold in queue ahead of open ledger. | |
| minimum_txn_in_ledger | src? | integer | Minimum transactions to target per ledger close. | |
| maximum_txn_in_ledger | src? | integer | Hard maximum transactions per ledger close. | |
| target_txn_in_ledger | src? | integer | Target transaction count for fee escalation calculations. | |
| minimum_escalation_multiplier | src? | integer | Minimum fee escalation multiplier. | |
| maximum_txn_per_account | src? | integer | Max queued transactions per account. | |
| minimum_queue_size | src? | integer | Minimum queue size regardless of load. | |
| retry_sequence_percent | src? | integer % | Retry percentage for out-of-sequence transactions. | |
| normal_consensus_increase_percent | src? | integer % | Queue size increase % per normal consensus round. | |
| slow_consensus_decrease_percent | src? | integer % | Queue size decrease % per slow consensus round. | |
| minimum_last_ledger_buffer | src? | integer | Buffer ledgers before LastLedgerSequence expiry. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [path_search] | 7 | integer | Default path search depth for standard requests. | |
| [path_search_fast] | 2 | integer | Reduced depth for fast/cheap path searches. | |
| [path_search_max] | 10 | integer | Hard ceiling on path search complexity. Prevents runaway searches. | |
| [path_search_old] | src? | 0 | 1 | Legacy path search algorithm. Deprecated. |
| Key | Default | Valid Values | Description | |
|---|---|---|---|---|
| hold_time | src? | integer (seconds) | How long transaction hashes are held to suppress relay duplicates. Increasing reduces duplicate processing at cost of memory. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [amendments] | empty | hash list | Explicitly enable amendments. Testnet/devnet only. | |
| [veto_amendments] | empty | hash list | Amendments this validator votes against. | |
| [amendment_majority_time] | 2 weeks | duration string | How long an amendment must hold >80% support before activating. | |
| [features] | src? | src? | New section in current Sections.h. Likely supplements or replaces [amendments]. Needs source investigation. | |
| [voting] | src? | key/value block | Voting configuration block. New in current header — undocumented. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [validator_token] | required on validators | token blob | Current ephemeral signing token from validator-keys-tool. Rotate periodically. | |
| [validator_keys] | required on validators | key list | Validator signing key(s). Replaces deprecated node_seed / validation_seed. | |
| [validator_key_revocation] | empty | revocation blob | Publish immediately if key is compromised. Alerts the network. | |
| [validator_list_sites] | vl.ripple.com + others | URL list | Where to fetch UNL. Override for Xahau or private networks. | |
| [validator_list_keys] | Ripple UNL signing key | key list | Keys that sign trusted UNL lists. | |
| [validator_list_threshold] | src? | integer % | Minimum % of trusted validators needed to trust a UNL. | |
| [vl] | src? | src? | New section in current Sections.h. Related to validator list handling — needs source investigation. | |
| [validators] | empty | pubkey [name] list | Hardcoded trusted validators. Use validator_list_sites instead. | |
| [validators_file] | empty | file path | External file of trusted validators. | |
| [node_seed] | deprecated | seed string | Deprecated. Use [validator_keys]. | |
| [validation_seed] | deprecated | seed string | Deprecated. Use [validator_token]. |
| Section / Key | Default | Valid Values | Description | |
|---|---|---|---|---|
| [server] | required | list of port section names | Declares all listening ports. Each name maps to a [port_xxx] stanza. | |
| [port_xxx] ip | required | IP | 0.0.0.0 | :: | Interface to bind. 0.0.0.0 = all IPv4, :: = all IPv4+IPv6. | |
| [port_xxx] port | required | integer | Port number to listen on. | |
| [port_xxx] protocol | required | http | https | ws | wss | peer | Protocols. Only one port can handle peer protocol. ws and http cannot mix with wss/https. | |
| [port_xxx] admin | empty (no admin) | IP list | 127.0.0.1 | IPs allowed to use admin RPC commands. Typically 127.0.0.1. | |
| [port_xxx] limit | 0 (unlimited) | integer | Max concurrent connections on this port. | |
| [port_xxx] send_queue_limit | 100 | 1 – 65535 | WebSocket send queue depth before disconnecting a client. | |
| [port_xxx] secure_gateway | empty | IP list | Trusted proxy IPs. Passes X-User / X-Forwarded-For headers, lifts resource limits. | |
| [port_grpc] | disabled | port section name | Enables gRPC interface for Clio server. | |
| [beta_rpc_api] | false | true | false | Enables experimental RPC methods not in stable API. | |
| [rpc_startup] | empty | JSON command list | RPC commands run at startup. Standard use: {"command":"log_level","severity":"warning"} | |
| [signing_support] | false | true | false | Allow clients to use this node to sign transactions. Disable on public nodes. |
| Key | Default | Valid Values | Description | |
|---|---|---|---|---|
| overlay | 1 | 0 | 1 | Include overlay peer data in crawl response. | |
| server | 1 | 0 | 1 | Include server_info in crawl response. | |
| counts | 0 | 0 | 1 | Include get_counts data in crawl response. Disabled by default. | |
| unl | 1 | 0 | 1 | Include UNL data in crawl response. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [relay_proposals] | true (1) | 0 | 1 | Relay consensus proposals to peers. Must be 1 on validators. | |
| [relay_validations] | true (1) | 0 | 1 | Relay validations to peers. Must be 1 on validators. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [ssl_verify] | 1 | 0 | 1 | Verify peer TLS certificates for outbound HTTPS connections. | |
| [ssl_verify_file] | empty | file path | Custom CA cert file for peer verification. | |
| [ssl_verify_dir] | empty | directory path | Directory of CA certs for peer verification. | |
| [sntp_servers] | time.windows.com + others | hostname list | NTP servers. Critical — clock skew causes validation failures and consensus issues. |
| Section | Default | Valid Values | Description | |
|---|---|---|---|---|
| [debug_logfile] | empty | file path | Separate debug log file. Debug level logging costs several GB/day — use warning in production. | |
| [fee_default] | 10 | integer (drops) | Base transaction fee in drops of XRP. | |
| [import_db] | empty | path/config block | Import ledger history from another node database. | |
| [perf] log_interval | src? | integer (seconds) | How often to emit StatsD performance metrics. | |
| [perf] prefix | src? | string | StatsD metric prefix. |
Require admin access — connect on a port with admin = 127.0.0.1.
CLI: rippled <command> ·
JSON-RPC: {"command": "name", ...}
| Command | Admin? | Description | Key Output Fields | |
|---|---|---|---|---|
| server_info | Public | Primary server status. Sync state, peers, load, build version, complete ledger range, last close time. | server_state, complete_ledgers, peers, load_factor, build_version, io_latency_ms | |
| get_counts | Yes | Internal cache stats and object counts. BUG RESEARCH Primary tool for node_size tuning. Shows cache hit rates, object counts, write queue depth. See Section 3 for full field reference. | SLE_hit_rate, node_hit_rate, treenode_cache_size, write_load, uptime | |
| consensus_info | Yes | Real-time consensus state snapshot. Current phase, proposers, positions. | phase, proposers, our_position, peer_positions | |
| fetch_info | Yes | Ledger sync status. What ledgers are being fetched and from which peers. | peers (with ledger fetch details) | |
| validator_info | Yes | This server's validator config. Confirms token and key are loaded correctly. | pubkey_validator, manifest, seq | |
| validators | Yes | Current full validator set with trust status. | count, trusted_validator_keys, signing_keys | |
| validator_list_sites | Yes | UNL fetch site status: last refresh time, expiry, fetch interval. | validator_sites (url, last_refresh_time, refresh_interval_min) | |
| feature | Yes | Amendment status. All known amendments, vote counts, enabled/vetoed/pending state. | features (per amendment: enabled, vetoed, supported, count, threshold) | |
| manifest | Public | Latest public key info for a known validator. Params: public_key. | master_key, signing_key, seq, signature | |
| Yes | Internal subsystem state dump. Low-level debugging. | varies by subsystem |
| Command | Admin? | Description | Key Output Fields | |
|---|---|---|---|---|
| log_level | Yes | Get or set log verbosity per partition. Partitions: Ledger, TxQ, Peer, Overlay, Consensus, etc. Levels: fatal | error | warning | info | debug | trace. Params: partition (optional), severity. | partition, severity (get); message (set) | |
| logrotate | Yes | Closes and reopens the debug log file. Run before external log rotation tools. | message: logrotate initiated | |
| ledger_request | Yes | Request a specific ledger version from peers. Forces acquisition of historical data. Params: ledger_index. | ledger_index, complete, peers_total | |
| ledger_cleaner | Yes | Configure the ledger cleaner to scan and repair corrupted ledger data. | message: Ledger cleaner queued | |
| can_delete | Yes | When advisory_delete=1, authorise online deletion up to a specified ledger. Params: can_delete (ledger index or "never"). | ledger_index (new can-delete value) |
| Command | Admin? | Description | Key Output Fields | |
|---|---|---|---|---|
| peers | Yes | All connected peers with connection details, sync state, and latency. | peers[]: address, public_key, ledger, load, latency, version | |
| connect | Yes | Force connection to a specific peer. Params: ip, port (optional). | message: connecting | |
| peer_reservations_add | Yes | Reserve a peer slot for a specific node pubkey. Reserved slots are never dropped by churn. Params: public_key, description (optional). | prev (previous reservation if existed) | |
| peer_reservations_del | Yes | Remove a peer reservation. Params: public_key. | prev | |
| peer_reservations_list | Yes | List all reserved peer slots. | reservations[] |
| Command | Admin? | Description | Key Output Fields | |
|---|---|---|---|---|
| stop | Yes | Gracefully shut down the rippled server. | message: ripple server stopping | |
| ledger_accept | Yes | Stand-alone mode only. Force-close and advance the current ledger. | ledger_current_index |
| Command | Admin? | Description | Key Output Fields | |
|---|---|---|---|---|
| wallet_propose | Yes* | Generate a new account key pair. Params: key_type (secp256k1 | ed25519), passphrase (optional). | account_id, master_key, master_seed, master_seed_hex, public_key, public_key_hex | |
| validation_create | Yes | Generate a node key pair. Note: validators should use validator-keys-tool for tokens instead of this method. | validation_public_key, validation_seed, validation_key |
| Command | Admin? | Description | Key Output Fields | |
|---|---|---|---|---|
| sign | Yes* | Sign a transaction. Returns tx_blob ready for submit. Requires signing_support=true or admin access. Params: tx_json, secret (or key_type + seed). | tx_blob, tx_json (with hash, SigningPubKey, TxnSignature) | |
| sign_for | Yes* | Contribute one signature to a multi-signature transaction. Params: account, tx_json, secret. | tx_blob, tx_json | |
| channel_authorize | Yes* | Sign a payment channel claim off-chain. Params: channel_id, amount, secret. | signature |
The primary diagnostic tool for node_size tuning research. Wait at least 10–15 minutes after sync before benchmarking — cache hit rates start low on cold start.
| Field | Type | Description & Research Relevance | |
|---|---|---|---|
| SLE_hit_rate | float % | State Ledger Entry cache hit rate. Primary benchmark metric. Directly driven by node_size cache allocation. Low rate = undersized cache for current workload. | |
| node_hit_rate | float % | Nodestore object cache hit rate. Should be >90% on a correctly sized node. Drops indicate cache pressure or undersized node_size. | |
| ledger_hit_rate | float % | Ledger header cache hit rate. How often recently-accessed ledgers are served from RAM. | |
| treenode_cache_size | integer | Current treecache object count. Directly set by node_size allocation. Compare medium vs large values to confirm whether allocation actually differs. | |
| treenode_track_size | integer | Tracked treecache objects. If approaching treenode_cache_size, eviction pressure is high — cache is too small for load. | |
| write_load | integer | Write queue depth to nodestore. High values = storage I/O bottleneck, not cache size. Distinguishes disk from memory issues. | |
| fullbelow_size | integer | Size of 'full below' cache — tracks subtrees known complete to avoid redundant fetches. | |
| openledger_size | integer | Objects held in the current open ledger. | |
| local_txs | integer | Transactions in local queue awaiting validation. | |
| uptime | seconds | Node uptime. Required context — low uptime means cold cache, hit rates will be artificially low. | |
| dbKBTotal | KB | Total nodestore database size on disk. | |
| dbKBLedger | KB | Ledger portion of nodestore database. | |
| dbKBTransaction | KB | Transaction portion of nodestore database. | |
| AL | integer | Available ledger versions in local history. |
Available without admin credentials via HTTP JSON-RPC or WebSocket. Clio servers provide the same API for historical queries with lower load on validators.
| Command | Category | Description & Key Parameters | |
|---|---|---|---|
| server_info | Server | General server status. Public version omits some admin fields. | |
| server_state | Server | Machine-readable server_info variant. | |
| server_definitions | Server | All ledger field definitions for the current protocol version. | |
| fee | Server | Current transaction fee and queue info: base_fee, median_fee, minimum_fee, open_ledger_fee. | |
| version | Server | API version info and supported range. | |
| ping | Server | Liveness check. Returns immediately. | |
| ledger | Ledger | Ledger header and optionally transactions or state data. Params: ledger_index, transactions, expand, full. | |
| ledger_closed | Ledger | Most recently closed ledger hash and index. | |
| ledger_current | Ledger | Current open ledger index. | |
| ledger_data | Ledger | Raw state data from a ledger. Paginate with marker. Expensive — avoid on production validators. | |
| ledger_entry | Ledger | Single ledger object by type and ID. Supports: account_root, offer, ripple_state, check, escrow, payment_channel, ticket, nft_offer, amm. | |
| account_info | Account | Account root: balance, sequence, flags, reserve. Params: account, ledger_index, queue, signer_lists. | |
| account_lines | Account | Trust lines for an account. Paginate with marker. Params: account, ledger_index, peer. | |
| account_channels | Account | Payment channels where account is source. | |
| account_currencies | Account | Currencies the account can send or receive. | |
| account_objects | Account | All ledger objects owned by account. Params: account, type, ledger_index, limit, marker. | |
| account_offers | Account | Open DEX offers placed by account. Params: account, ledger_index, limit, marker. | |
| account_tx | Account | Transaction history. Params: account, ledger_index_min/max, limit, marker, forward. | |
| gateway_balances | Account | Issued currency totals for an issuer. Params: account, hotwallet. | |
| noripple_check | Account | Identify trust line No-Ripple flag configuration issues. | |
| transaction / tx | Transaction | Single transaction by hash. Params: transaction (hash), binary, include_deleted. | |
| submit | Transaction | Submit a signed transaction blob. Returns preliminary result before validation. Params: tx_blob. | |
| submit_multisigned | Transaction | Submit a multi-signed transaction. Params: tx_json. | |
| simulate | Transaction | Dry-run a transaction without submitting. Returns what the result would be. | |
| book_offers | DEX | Current order book for a currency pair. Params: taker_pays, taker_gets, limit. | |
| path_find | Paths | WebSocket only. Subscribe to path updates for a payment. Continuously updated until closed. | |
| ripple_path_find | Paths | One-shot path find. Less resource-intensive than path_find. Params: source_account, destination_account, destination_amount. | |
| channel_verify | Channels | Verify a payment channel claim signature. | |
| subscribe | Streams | Subscribe to event streams: ledger, transactions, transactions_proposed, server, peer_status, validations, manifests, book_changes. | |
| unsubscribe | Streams | Cancel a stream subscription. | |
| nft_info | NFT | Info about a specific NFT by NFTokenID. | |
| nft_buy_offers | NFT | Buy offers for a specific NFT. | |
| nft_sell_offers | NFT | Sell offers for a specific NFT. | |
| nfts_by_issuer | NFT | NFTs minted by an issuer. Params: issuer, nft_taxon, limit, marker. | |
| amm_info | AMM | State of an Automated Market Maker pool. Params: amm_account or asset/asset2 pair. | |
| deposit_authorized | Misc | Check if source account is authorized to send to destination (DepositAuth). | |
| random | Misc | Returns a cryptographically random 256-bit hex value from the server. |
| Flag / Mode | Description |
|---|---|
| rippled | Start in daemon mode (default). Reads rippled.cfg from standard locations. |
| --conf <path> | Specify config file path explicitly. |
| --fg | Run in foreground — don't daemonize. Useful for debugging. |
| -q | Quiet mode — suppress startup output. |
| --silent | Suppress all console output. |
| -v / --verbose | Verbose output. |
| --version | Print build version, Git commit hash, and build branch. |
| -h / --help | Print usage statement. |
| -u / --unittest | Run unit tests and print results. |
| rippled <command> | Client mode: connect to running rippled and issue RPC command. Examples: rippled server_info rippled get_counts rippled peers rippled stop |
| --standalone / -a | Run in stand-alone mode: no network, no consensus. For testing. |
| --start | Start with a fresh ledger in standalone mode. |
| --ledger <file> | Load ledger from file (standalone / testing mode). |
| --import | Import history from another node database. |
Official guidance from xrpl.org Capacity Planning docs. Note: large is explicitly listed as not recommended — it performs worse than huge in most circumstances.
| node_size | RAM Required | Recommended Use | Notes |
|---|---|---|---|
| tiny | < 8 GB | Not recommended | May fail to sync on a busy network. |
| small | 8 GB | Test servers / occasional use | |
| medium | 16 GB | Default in rippled-example.cfg | Auto-selected for 16GB systems. BUG: also auto-selected for 4-core/32GB machines. |
| large | 32 GB | NOT RECOMMENDED | Explicitly listed as underperforming huge in most circumstances. Auto-detection may collapse this to medium. |
| huge | 64 GB | Recommended for all production | Only setting to use for mainnet stability if ≥64GB RAM available. |
Files to read in the XRPLF/rippled repository to confirm undocumented defaults and investigate the node_size bug.