docs: Document additional config settings - #8148
Conversation
Add commented examples for supported settings that were missing from the example config.
There was a problem hiding this comment.
🟡 Changes recommended
The new [elb_support] documentation omits an availability condition actually enforced by serverOkay() (“Too much load”), so the operator-facing description is incomplete.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the shipped example configuration files to document additional operator-facing settings that are already parsed/used by the server but previously undocumented in cfg/xrpld-example.cfg and cfg/validators-example.txt, with no behavioral changes (all additions are commented).
Changes:
- Documents peer/overlay-related settings including
[peers_in_max],[peers_out_max],[network_quorum],[reduce_relay], and[hashrouter]. - Documents additional database-related settings including
[ledger_tx_tables]/use_tx_tables, RocksDB tuning keys under[node_db], and[sqdb]backend. - Documents amendment/feature-related settings and adds
[validator_keys]documentation in the validators example file.
File summaries
| File | Description |
|---|---|
| cfg/xrpld-example.cfg | Adds commented documentation for several previously-undocumented config sections/keys (peering, relay/hashrouter tuning, DB toggles/tuning, amendments/features, misc). |
| cfg/validators-example.txt | Adds commented documentation for the [validator_keys] section and how it is merged/used at startup. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🔵 Needs a closer look
The new docs for [peers_in_max]/[peers_out_max] incorrectly imply [peers_max] is an invalid combination, but the parser merely gives [peers_max] precedence and ignores the new keys without error.
Review details
Suppressed comments (2)
Previously missed (1) — in code that hasn't changed since the last review.
cfg/xrpld-example.cfg:471
- The text says the legacy [peers_max] "must not be set", but the parser does not reject that combination; it simply prioritizes [peers_max] and ignores [peers_in_max]/[peers_out_max] when [peers_max] is present. Updating this wording avoids implying a startup error that won't happen.
This issue also appears on line 484 of the same file.
cfg/xrpld-example.cfg:487
- The text says the legacy [peers_max] "must not be set", but the parser does not reject that combination; it simply prioritizes [peers_max] and ignores [peers_in_max]/[peers_out_max] when [peers_max] is present. Updating this wording avoids implying a startup error that won't happen.
# Valid range: 10 to 1000. If set, you must also set [peers_in_max], and the
# legacy [peers_max] must not be set (when present, [peers_max] takes
# precedence and this setting is ignored). If unset, the server
# auto-configures a limit based on node size.
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟡 Changes recommended
A couple of newly added documentation statements about peer-limit defaults and validator configuration are inaccurate/misleading relative to the current implementation.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
Previously missed (1) — in code that hasn't changed since the last review.
cfg/validators-example.txt:30
- The note implies that providing [validator_list_keys] alone is sufficient as a “source of validators”, but this section only supplies trusted publisher keys; validator lists are fetched from [validator_list_sites]. Rewording this avoids suggesting that keys alone will produce a validator set.
cfg/xrpld-example.cfg:487
- Same as above: the default peer limits are not derived from node size; when unset the server falls back to [peers_max] (and peerfinder defaults if [peers_max] is unset).
# Valid range: 10 to 1000. If set, you must also set [peers_in_max]. If the
# legacy [peers_max] is set, it takes precedence and this setting is
# ignored. If unset, the server auto-configures a limit based on node
# size.
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
The new RocksDB tuning documentation incorrectly states several keys are auto-sized from [node_size] when unset, which does not match the implementation.
Review details
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
cfg/xrpld-example.cfg:1261
- The text here says RocksDB tuning keys (like open_files and file_size_mb) are auto-sized from [node_size] when unset, but the implementation only auto-populates cache_mb (see src/xrpld/app/misc/SHAMapStoreImp.cpp:116-127) and the RocksDB backend only applies open_files / file_size_mb if they are explicitly present (src/libxrpl/nodestore/backend/RocksDBFactory.cpp:119-156). As written, this can mislead operators into thinking these values have node-size defaults in xrpld.
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🔵 Needs a closer look
A couple of newly added documentation blocks are incomplete/misaligned with the implementation and should be corrected to avoid misleading operators.
Review details
Suppressed comments (2)
Previously missed (2) — in code that hasn't changed since the last review.
cfg/xrpld-example.cfg:692
- The [hashrouter] section currently suggests these settings are generally suitable to tune, but the implementation explicitly warns they are intentionally undocumented and should not be changed without a strong reason and network-wide coordination (see include/xrpl/core/HashRouter.h:94-97). Adding a caution here would prevent operators from inadvertently diverging from network defaults.
cfg/xrpld-example.cfg:1397 - Disabling use_tx_tables affects more than just the tx/account_tx/tx_history RPC commands: the "account_history_tx_stream" subscribe option is also gated behind useTxTables() (see src/xrpld/rpc/handlers/subscribe/Subscribe.cpp:249-252). The documentation should mention this so operators aren’t surprised.
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Lite
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only (commented-out examples) and the documented defaults/constraints align with the referenced parsing/usage code paths.
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Lite
Summary
The server reads a number of configuration settings that the shipped example
config (
cfg/xrpld-example.cfg) andcfg/validators-example.txtnever mention,so operators can only discover them by reading the source. This PR adds
commented-out documentation for the operator-facing ones, with every value,
default, and constraint verified against the parsing code.
Everything added is commented out, so there is no behavior change.
How these were found
Rather than work from the existing docs, each setting was found by enumerating
every config read-site in
src/xrpldandsrc/libxrpl(section(...),valueOr/value_or,exists,get/getIfExists/get<T>,set(...),getSingleSection,legacy, andoperator[], resolving the section and keyconstants in
include/xrpl/config/Constants.h) and diffing that set againsteverything documented in the two shipped files. Read-sites in
src/testwereexcluded, so every setting below is read by production code. Defaults and
constraints were then read directly from the source lines cited in the table.
Changes
cfg/xrpld-example.cfgPeer Protocol:
[peers_in_max]/[peers_out_max]: inbound/outbound peer connectionlimits. Must be set together; ignored if the legacy
[peers_max]is set.[network_quorum]: minimum connected peers before joining consensus(default
1; not the UNL/validation quorum).[reduce_relay]: bandwidth-reduction options:vp_base_squelch_enable(default off),
vp_base_squelch_max_selected_peers(5),tx_enable(off),tx_min_peers(20),tx_relay_percentage(25),tx_metrics(off). Theolder
vp_enableis documented as a deprecated alias.[hashrouter]:hold_time(default 300s, min 12) andrelay_time(default 30s, min 8, must not exceed
hold_time) for duplicate-messagesuppression/relay. Documented with a caution against changing them without
network-wide coordination, mirroring the note in the code.
Database:
[ledger_tx_tables]use_tx_tables: default1;0disables the SQLitetransaction index tables, after which
tx,account_tx,tx_history, andthe
account_history_tx_streamsubscribe option returnnotEnabled. Doesnot stop transactions being stored in ledgers.
[node_db]RocksDB-only tuning keys:cache_mb,open_files,file_size_mb,file_size_mult,bg_threads,high_threads,hard_set(documented as optional; only
cache_mbis sized from[node_size]whenunset, the rest fall back to RocksDB library defaults).
[sqdb]backend: selects the relational-database backend; onlysqliteis supported (and is the default).
Voting / amendments:
[amendments]/[veto_amendments]: amendments this server votes for oragainst. Each line is a 64-char hex amendment ID followed by its name.
[amendment_majority_time]: how long an amendment must hold majority beforeactivation (default 2 weeks, min 15 minutes).
[features]: force-enables features in locally-built ledgers. Documentedwith a clear note that it is for standalone/testing only and can cause a
networked server to lose sync or stop processing (downtime).
Misc:
[sweep_interval]: cache sweep interval in seconds (10 to 600; derived from[node_size]when unset).[elb_support]: default0; gatesserverOkay()load-balancer healthreporting.
cfg/validators-example.txt[validator_keys]: an additional list of validator public keys, merged with[validators]at startup (kept for backward compatibility). Documentedalongside its sibling validator sections.
How to verify
peers_in_max/peers_out_maxsrc/xrpld/core/detail/Config.cpp:547-577network_quorumsrc/xrpld/core/detail/Config.cpp:676reduce_relaykeyssrc/xrpld/core/detail/Config.cpp:794-861vp_enabledeprecatedvp_base_squelch_enablesrc/xrpld/core/detail/Config.cpp:801-813hashrouterhold/relaysrc/xrpld/app/misc/detail/setup_HashRouter.cpp:26-48; defaultsinclude/xrpl/core/HashRouter.h:112,117use_tx_tablessrc/xrpld/core/detail/Config.cpp:413-414; gated insrc/xrpld/app/rdb/backend/detail/SQLiteDatabase.cppnode_dbRocksDB keyscache_mbnode-size derivedsrc/libxrpl/nodestore/backend/RocksDBFactory.cpp:117-170;src/xrpld/app/misc/SHAMapStoreImp.cpp:117-127sqdbbackendsqlite; onlysqliteacceptedsrc/libxrpl/rdb/SociDB.cpp:55-59amendments/veto_amendmentssrc/xrpld/app/main/Application.cpp:1245-1247; parsesrc/xrpld/app/misc/detail/AmendmentTable.cpp:50-80amendment_majority_timesrc/xrpld/core/detail/Config.cpp:959-993; defaultinclude/xrpl/protocol/SystemParameters.h:81featuressrc/xrpld/core/detail/Config.cpp:1164-1176sweep_intervalsrc/xrpld/core/detail/Config.cpp:740-747; usesrc/xrpld/app/main/Application.cpp:929-931elb_supportsrc/xrpld/app/main/Application.cpp:2106validator_keys[validators]src/xrpld/core/detail/Config.cpp:1080-1153Notes for reviewers
operators (the raw
options/bbt_optionsstrings,filter_bits,filter_full,block_size,universal_compaction, andrq_bundle) wereintentionally left undocumented to keep the example file focused. They can be
added on request.
Type of change
docs:documentation only, no functional change.