Add Running Genesis Mode HOWTO - #2037
Conversation
dnadales
added
no changelog
skip-tests
|
lgtm, and indeed there is documentation on configuring and running in |
| "UseTraceDispatcher": true, | ||
| "TurnOnLogging": true |
There was a problem hiding this comment.
Last two are generic tracing options, rather than something Genesis related, using UseTraceDispatcher is probably not even necessary, e.g. one can run the new tracing system in a mode which traces to stdout rather than through the TraceDispatcher.
There was a problem hiding this comment.
Right — these are generic tracing options, not Genesis prerequisites, so they've been dropped from the required-config section.
Checking against master, the logging switch was in fact removed in 289dee332 (2026-05-18): UseTraceDispatcher and TurnOnLogging are no longer parsed and the new tracing system runs unconditionally, so nothing needs enabling.
The tracer section now just notes that and points out the switch is gone on current nodes.
Fixed in d003d27.
| ```json | ||
| "HostIPv4Addr": "0.0.0.0", | ||
| "HostIPv6Addr": "::" | ||
| ``` |
There was a problem hiding this comment.
I never used these config options (are you sure they exist?), there are CLI options for them in the node.
There was a problem hiding this comment.
Good catch — those config.json keys don't exist.
The host addresses come only from the --host-addr / --host-ipv6-addr CLI options (Cardano/Node/Parsers.hs); there's no HostIPv4Addr/HostIPv6Addr in the config parser, and SocketConfig has no FromJSON instance.
The section now uses the CLI options instead.
The IPv6 guidance was also corrected: the node dials literal IPv6 snapshot peers regardless of --host-ipv6-addr (the local address only affects socket binding and the DNS lookup family), so omitting it doesn't make the node skip them — the fix is host routing or dropping the IPv6 peers from the snapshot.
Fixed in d003d27.
Operational guide for running, configuring, and debugging Genesis-mode nodes. Covers host networking (IPv4/IPv6), small-testnet peer selection overrides (including MinBigLedgerPeersForTrustedState), sync stall diagnosis, and tracer configuration.
Address review feedback and re-verify every claim against cardano-node origin/master and ouroboros-network source. - ConsensusMode is the only field that enables Genesis. UseTraceDispatcher and TurnOnLogging are not Genesis prerequisites; they are generic tracing options and have been removed from cardano-node (the new tracing system is now unconditional). - Host addresses come from the --host-addr / --host-ipv6-addr CLI options, not HostIPv4Addr / HostIPv6Addr config.json keys (which do not exist). Rewrite the IPv6 guidance: the node dials literal IPv6 snapshot peers regardless of --host-ipv6-addr; the remedy is host routing or removing the IPv6 peers from the snapshot. - The GSM runs in both Praos and Genesis modes; only CSJ and GDD are Genesis-only. Note MinBigLedgerPeersForTrustedState and LowLevelGenesisOptions as the other Genesis-specific config fields. - The peer snapshot is an optional peerSnapshotFile, not a required peer-snapshot.json. - Fix tracer claims: PeerStarvedUs is silenced by default until BlockFetch.Decision is raised; DMaximum is not required for per-peer decline reasons; the GDD debug info is the TraceGDDDebugInfo kind under Consensus.GDD.TraceGDDEvent; CSJ InitializedAsDynamo needs Genesis mode, a registered peer, and a Debug override. - Clarify that useLedgerAfterSlot: -1 disables ledger peers.
bb53758 to
d003d27
Compare
jasagredo
left a comment
jasagredo
left a comment
There was a problem hiding this comment.
I think this is in general useful and describes possible causes that would have taken me quite some time to figure out.
The only remark is that this might not belong to Consensus, but instead to the node wiki, dev portal, or some such.
| Use Genesis mode on **relay nodes and syncing nodes** that connect to the public network. | ||
|
|
||
| Use Praos mode on **block-producing nodes** that connect only to trusted local relays. | ||
| Setting `useLedgerAfterSlot: -1` disables ledger peers, so the node uses only its configured roots (`-1` turns ledger peers off; `0` would mean "always use the ledger"). |
There was a problem hiding this comment.
Unsure where this config is? I don't think it is in the configuration file. Perhaps in the topology?
| "MinBigLedgerPeersForTrustedState": 1, | ||
| "SyncTargetNumberOfRootPeers": 0, | ||
| "SyncTargetNumberOfKnownPeers": 1, | ||
| "SyncTargetNumberOfEstablishedPeers": 1, | ||
| "SyncTargetNumberOfActivePeers": 1, | ||
| "SyncTargetNumberOfKnownBigLedgerPeers": 1, | ||
| "SyncTargetNumberOfEstablishedBigLedgerPeers": 1, | ||
| "SyncTargetNumberOfActiveBigLedgerPeers": 1 |
There was a problem hiding this comment.
These will not be top-level fields anymore after cardano-config
| The overrides below use cardano-node's new tracing system, which is always on — no separate flag enables it. | ||
| (Older nodes gated it behind `UseTraceDispatcher`/`TurnOnLogging`, both generic and defaulting to on; current cardano-node has removed that switch.) |
There was a problem hiding this comment.
Being the default, we probably can omit this info
## Summary Adds a reference doc that maps the Genesis feedback loop and GSM states to the trace events a running node emits. It lets you locate a sync stall against the components: stuck in PreSyncing, stuck in Syncing, bouncing, and the healthy signature. ## Context Supersedes #2037. That PR was an operational "how to run nodes" guide. The configuration, tuning, and tracer setup belong on the developer portal, which already documents Genesis configuration. This doc keeps only the consensus-side model and links to the portal for the fixes. Companion developer-portal PR: cardano-foundation/developer-portal#1874, which adds the operator-facing configuration, tuning, and tracer setup. That PR links back to this page, so it should merge after this one is deployed. Trace namespaces were verified against cardano-node master.
4 participants
Summary
Motivation
The existing Genesis documentation (
genesis_design.md) describes the design for implementers.There was no documentation for people actually running, configuring, or debugging Genesis-mode nodes.
This gap became apparent while investigating sync stalls on the dijkstra and leios testnets (3 relays each).
The root cause was that
MinBigLedgerPeersForTrustedState(default 5) prevents the HAA from being satisfied when the network has fewer than 5 big ledger peers — a fact not documented anywhere.Lowering
SyncTargetNumberOfActiveBigLedgerPeersalone is not sufficient; the HAA gate must also be lowered.The new doc distills the debugging knowledge acquired during that investigation into reusable guidance.