Configuration

Dugite reads a JSON configuration file that controls network settings, genesis file paths, P2P parameters, and tracing options. The format is compatible with the cardano-node configuration format.

Configuration File Format

The configuration file uses PascalCase keys (matching the cardano-node convention). This is config/preview/config.json as shipped in the repository:

{
  "Network": "Testnet",
  "NetworkMagic": 2,
  "DiffusionMode": "InitiatorAndResponder",
  "ByronGenesisFile": "byron-genesis.json",
  "ByronGenesisHash": "81cf23542e33d64c541699926c2b5e6e9c286583f0c8a3fb5f22ea7b352dd174",
  "ShelleyGenesisFile": "shelley-genesis.json",
  "ShelleyGenesisHash": "363498d1024f84bb39d3fa9593ce391483cb40d479b87233f868d6e57c3a400d",
  "AlonzoGenesisFile": "alonzo-genesis.json",
  "ConwayGenesisFile": "conway-genesis.json",
  "TargetNumberOfRootPeers": 60,
  "TargetNumberOfActivePeers": 15,
  "TargetNumberOfEstablishedPeers": 30,
  "TargetNumberOfKnownPeers": 85,
  "TargetNumberOfActiveBigLedgerPeers": 5,
  "TargetNumberOfEstablishedBigLedgerPeers": 10,
  "TargetNumberOfKnownBigLedgerPeers": 15,
  "MinSeverity": "Info",
  "LogDirective": "info",
  "MetricsPort": 12796,
  "ExperimentalHardForksEnabled": true
}

Unknown keys are ignored. The node's deserializer does not reject fields it does not recognise, so a typo in a key name silently leaves the default in force with no warning. Run dugite-config validate <file> to have unknown keys reported — see Configuration Editor.

Fields Reference

Network Settings

EnableP2P is not a Dugite config key. Dugite is always P2P; there is no non-P2P path to switch off. If your config file carries EnableP2P (from a cardano-node 8.x config) the node ignores it silently.

Protocol

These three are inert. They are parsed so a cardano-node config file drops in without error, but nothing in the workspace reads them — Dugite always sends the network magic in the N2N handshake. NetworkMagic is the field that actually decides which network you join.

Genesis Files

Genesis file paths are resolved relative to the directory containing the configuration file. For example, if your config is at /opt/cardano/config.json and specifies "ShelleyGenesisFile": "shelley-genesis.json", Dugite will look for /opt/cardano/shelley-genesis.json.

At startup the node checks that every configured genesis file exists (resolved against the config file's directory) and that every configured hash is exactly 64 hex characters. Either check failing is a fatal startup error naming the era.

Tip: Genesis files for each network can be downloaded from the Cardano Operations Book.

P2P Parameters

These parameters control the P2P peer governor's target counts, matching the cardano-node defaults. The governor continuously works to maintain these targets by promoting/demoting peers and discovering new ones.

Two of these are advisory in Dugite rather than direct policy levers: TargetNumberOfRootPeers is validated and exported as a Prometheus gauge, but root-peer connectivity is actually driven per-group by the topology's hotValency / warmValency; and TargetNumberOfKnownBigLedgerPeers is not enforced as a separate cap, because the known set as a whole is bounded by TargetNumberOfKnownPeers and selectively forgetting scarce big ledger peers would hurt Genesis sync.

Genesis-mode sync targets

A second target set applies while the node is in Genesis-mode bulk sync. It is parsed and validated unconditionally, but only takes effect when ConsensusMode is "Genesis".

Startup validation

Both target sets are checked at startup against the same predicates as Haskell's sanePeerSelectionTargets, and a violation is a fatal startup error naming the set ([deadline] or [sync]):

• active <= established <= known, and root <= known
• activeBigLedger <= establishedBigLedger <= knownBigLedger
• active <= 100, established <= 1000, known <= 10000 (and the same three ceilings for the big-ledger-peer counts)

Churn

Ouroboros Genesis Tuning

LowLevelGenesisOptions mirrors cardano-node's object of the same name and is only consulted when ConsensusMode is "Genesis". Omit the whole object to get the upstream defaults.

"LowLevelGenesisOptions": {
  "EnableCSJ": true,
  "EnableLoEAndGDD": true,
  "EnableLoP": true,
  "BlockFetchGracePeriod": 10,
  "BucketCapacity": 100000,
  "BucketRate": 500,
  "CSJJumpSize": 4320,
  "GDDRateLimit": 1.0
}

Checkpoints

Connection Management

AcceptedConnectionsLimit also accepts the older long key names (acceptedConnectionsHardLimit, acceptedConnectionsSoftLimit, acceptedConnectionsDelay) as aliases.

The following four keys are parsed for cardano-node config-file compatibility but not currently enforced. Setting them changes nothing; they are reserved so that a cardano-node config drops in without a parse error.

Metrics, RPC, and Storage

Effective metrics port, highest precedence first: --no-metrics → 0; --metrics-port <PORT>; TurnOnLogMetrics: false → 0; MetricsPort; otherwise 12796. Note that an explicit --metrics-port wins even over TurnOnLogMetrics: false.

Tracing

Log Level Control

Verbosity is resolved with this precedence, highest first:

1. RUST_LOG environment variable
2. --log-level CLI flag
3. LogDirective config field
4. MinSeverity config field

# Via CLI flag
dugite-node run --log-level debug ...

# Via environment variable (takes priority over --log-level)
RUST_LOG=info dugite-node run ...

# Debug only for specific crates
RUST_LOG=dugite_network=debug,dugite_consensus=debug dugite-node run ...

Because the config file is read after the tracing subscriber is constructed, the config-file values are applied via a live filter reload immediately after startup — but only when neither RUST_LOG nor --log-level is set, so an explicit operator override is never clobbered by the file.

That guard applies at startup only. A later SIGHUP applies LogDirective / MinSeverity unconditionally, so a reload will override a level you set on the command line or in the environment.

Dugite supports multiple log output targets (stdout, file, journald) and file rotation. See Logging for full details on output configuration.

Live Reload (SIGHUP)

Sending SIGHUP re-reads both the config file and the topology file. Changed fields are partitioned into those that can be applied live and those that need a restart; restart-required changes are logged as warnings and the reloadable ones are still applied.

Hot-reloadable: all seven TargetNumberOf* deadline targets, ChurnIntervalNormalSecs, ChurnIntervalSyncSecs, LogDirective, MinSeverity.

Restart required: Network, NetworkMagic, every genesis file path and hash, MetricsPort, TurnOnLogMetrics, DiffusionMode, ExperimentalHardForksEnabled, ConsensusMode — plus everything set on the command line (database and socket paths, listen address and port, KES/VRF/OpCert paths).

kill -HUP $(pgrep -x dugite-node)

Stopping the Node

Always stop the node with SIGTERM (or SIGINT / Ctrl-C), never SIGKILL.

kill -TERM $(pgrep -x dugite-node)     # correct
kill -9    $(pgrep -x dugite-node)     # do not do this

On SIGTERM the node demotes its peers, flushes storage, and writes a final ledger snapshot. A hard kill skips all of that and risks damaging the active ImmutableDB chunk's secondary index. Since v2.4.0 the node reconciles that damage at open — verifying the tail chunk by CRC, truncating to the verified prefix, and quarantining an index-less tail chunk as .chunk.orphaned — but recovery still costs the un-flushed blocks, and damage below the tail chunk is a hard InconsistentChunk error rather than something the node repairs.

A second SIGINT/SIGTERM during shutdown forces an immediate exit, matching cardano-node's behaviour, so you never need kill -9 to get out of a wedged shutdown.

ChainDB::open takes an exclusive advisory flock on <database-path>/lock, so a second process pointed at the same directory fails fast and names the pid already holding it, instead of two nodes silently interleaving writes.

Minimal Configuration

The smallest viable configuration file specifies only the network:

{
  "Network": "Testnet",
  "NetworkMagic": 2
}

All other fields use the defaults tabulated above. Note that with no genesis files specified the node falls back to built-in default protocol parameters, which will not match a real network — for anything beyond a smoke test, point at the genesis files for the network you are joining.

Format Support

The parser picks its format from the file extension: .json is parsed as cardano-node-compatible JSON, and anything else is parsed as TOML. If the path does not exist at all, the node starts on built-in defaults rather than failing — so a typo in --config produces a mainnet-default node, not an error.

Editing Configuration Interactively

dugite-config is a standalone TUI for browsing and editing these files with per-field type validation, tuning hints, a diff view, and a save-and-SIGHUP live reload. See Configuration Editor (dugite-config).