Directory / technical-docs / understanding-config-files.md

You are browsing a mirror of a file hosted on GitHub. View original

Understanding your configuration files and how to use them:

UPDATED FOR TAG: 1.14.2

The topology.json file

Tells your node to which nodes in the network it should talk to. A minimal version of this file looks like this:

{
  "Producers": [
    {
      "addr": "x.x.x.x",
      "port": 3001,
      "valency": 1
    }
  ]
}
  • This means that your node will contact node at ip x.x.x.x on port 3001.

  • valency tells the node how many connections your node should have. It only has an effect for dns addresses. If a dns address is given, valency governs to how many resolved ip addresses should we maintain active (hot) connection; for ip addresses, valency is used as a boolean value, where 0 means to ignore the address.

Your block-producing node must ONLY talk to your relay nodes, and the relay node should talk to other relay nodes in the network. Go to our telegram channel to find out IP addresses and ports of peers.

The genesis.json file

The genesis file is generated with the cardano-cli by reading a genesis.spec.json file, which is out of scope for this document. But it is important because it is used to set:

  • genDelegs, a mapping from genesis keys to genesis delegates.
  • initialFunds, a mapping from the initial addresses to the initial values at those address.
  • MaxLovelaceSupply, the total amount of lovelaces in the blockchain.
  • startTime, the time of slot zero.

The genesis.json file looks like the one below.

    {
    "activeSlotsCoeff": 0.05,
    "protocolParams": {
    "poolDeposit": 500000000,
    "protocolVersion": {
        "minor": 0,
        "major": 0
    },
    "minUTxOValue": 0,
    "decentralisationParam": 1,
    "maxTxSize": 16384,
    "minPoolCost": 0,
    "minFeeA": 44,
    "maxBlockBodySize": 65536,
    "minFeeB": 155381,
    "eMax": 18,
    "extraEntropy": {
        "tag": "NeutralNonce"
    },
    "maxBlockHeaderSize": 1100,
    "keyDeposit": 400000,
    "nOpt": 250,
    "rho": 0.0022,
    "tau": 0.05,
    "a0": 0.3
    },
    "protocolMagicId": 42,
    "genDelegs": {
    "acded41a3329534b4a138a6262fc89ed84ab84a47439820027a1cfde": {
        "delegate": "3006bbc11b9587f758f818e55d376173894f3119fa9f3bb506b39014",
        "vrf": "4591768a404433121c891f4dcc72db18945f8f05c51b990c2ef32135f585ae5b"
    },
    "0e549da1e802e993fd67d0da974f8d64148417ded9ace34a38ee842e": {
        "delegate": "17d2ab1bd33faeb975ce82f531cffb4c956acf14fc5fe62a30209b55",
        "vrf": "f086cf388d1c9de15b5100da4198b5724ac65bab87ee25d1a7b34cbebd0dad36"
    },
    "a8fc4c8befb7a818fb86e68ec2bab42e90efb7833d6854e2d29570e7": {
        "delegate": "65a6cf060d4b537ecca6b09690740cf7633941dd1de086c06652461f",
        "vrf": "f92d64e5c607c3ff94ca8614781c5fc015d12c72c642b919e4d5665e765295b1"
    }
    },
    "updateQuorum": 3,
    "networkId": "Testnet",
    "initialFunds": {
    "60c307230dbe3be32364f2c3386c61b9a065b36635705f6feac72c4802": 1e+16,
    "60be9af17be11a9c959721278f7a4be0161688df2ff1965444f8f50d53": 1000000000000000
    },
    "maxLovelaceSupply": 45000000000000000,
    "networkMagic": 42,
    "epochLength": 21600,
    "staking": {
    "pools": {},
    "stake": {}
    },
    "systemStart": "2020-06-28T21:00:00Z",
    "slotsPerKESPeriod": 3600,
    "slotLength": 1,
    "maxKESEvolutions": 120,
    "securityParam": 108
    }

Here is a brief description of each parameter. You can learn more in the spec

PARAMETERMEANING
activeSlotsCoeffThe proportion of slots in which blocks should be issued.
poolDecayRateDecay rate for pool deposits
poolDepositThe amount of a pool registration deposit
protocolVersionAccepted protocol versions
decentralisationParamPercentage of blocks produced by federated nodes
maxTxSizeMaximal transaction size
minPoolCostStake pools cannot register/re-register their stake cost below this value
minFeeAThe linear factor for the minimum fee calculation
maxBlockBodySizeMaximal block body size
keyMinRefundThe minimum percent refund guarantee
minFeeBThe constant factor for the minimum fee calculation
maxBlockBodySizeMaximal block body size
keyMinRefundThe minimum percent refund guarantee
minFeeBThe constant factor for the minimum fee calculation
eMaxEpoch bound on pool retirement
extraEntropyWell, extra entropy =)
maxBlockHeaderSize
keyDepositThe amount of a key registration deposit
keyDecayRateThe deposit decay rate
nOptDesired number of pools
rhoMonetary expansion
poolMinRefundThe minimum percent pool refund
tauTreasury expansion
a0Pool’s pledge influence
protocolMagicIdTo identify the testnets
systemStartTime of slot 0
genDelegsMapping from genesis keys to genesis delegate
updateQuorumDetermines the quorum needed for votes on the protocol parameter updates
maxMajorPVProvides a mechanism for halting outdated nodes
initialFundsMapping address to values
maxLovelaceSupplyThe total number of lovelace in the system, used in the reward calculation.
networkMagicTo identify the testnet
epochLengthNumber of slots in an epoch.
stakingInitial delegation
slotsPerKESPeriodNumber of slots in an KES period
slotLengthin seconds
maxKESEvolutionsThe maximum number of time a KES key can be evolved before a pool operator must create a new operational certificate
securityParamSecurity parameter k

The config.json file

The default config.json file that we downloaded is shown below.

This file has 4 sections that allow you to have full control on what your node does and how the informtion is presented.

NOTE Due to how the config.json file is generated, fields on the real file are shown in a different (less coherent) order. Here we present them in a more structured way

1 Basic Node Configuration.

First section relates the basic node configuration parameters. Make sure you have to TPraosas the protocol, the correct path to the shelley_testnet-genesis.json file, RequiresMagicfor its use in a testnet. Note that in this example we are using the SimpleView. This will send the output to stdout. Other option is LiveView which uses a terminal multiplexer to generate a fancy view. We will cover this topic later.

{
  "Protocol": "TPraos",
  "GenesisFile": "shelley_testnet-genesis.json",
  "RequiresNetworkMagic": "RequiresMagic",

2 Update parameteres

This protocol version number gets used by block producing nodes as part of the system for agreeing on and synchronising protocol updates.You just need to be aware of the latest version supported by the network. You dont need to change anything here.

  "ApplicationName": "cardano-sl",
  "ApplicationVersion": 0,
  "LastKnownBlockVersion-Alt": 0,
  "LastKnownBlockVersion-Major": 0,
  "LastKnownBlockVersion-Minor": 0,

3 Tracing

Tracers tell your node what information you are interested in when logging. Like switches that you can turn ON or OFF according the type and quantity of information that you are interesetd in. This provides fairly coarse grained control, but it is relatively efficient at filtering out unwanted trace output.

The node can run in either the SimpleView or LiveView. The SimpleView just uses standard output, optionally with log output. The LiveView is a text console with a live view of various node metrics.

TurnOnLogging: Enbles or disables logging overall.

TurnOnLogMetrics: Enable the collection of various OS metrics such as memory and CPU use. These metrics can be directed to the logs or monitoring backends.

setupBackends, defaultBackends, hasEKGand hasPrometheus: The system supports a number of backends for logging and monitoring. This settings list the the backends available to use in the configuration. The logging backend is called Katip. Also enable the EKG backend if you want to use the EKG or Prometheus monitoring interfaces.

setupScribes and defaultScribes: For the Katip logging backend we must set up outputs (called scribes) The available types of scribe are:

  • FileSK: for files
  • StdoutSK/StderrSK: for stdout/stderr
  • JournalSK: for systemd’s journal system
  • DevNullSK
  • The scribe output format can be ScText or ScJson.

rotation The default file rotation settings for katip scribes, unless overridden in the setupScribes above for specific scribes.

  "TurnOnLogging": true,
  "TurnOnLogMetrics": true,
  "ViewMode": "SimpleView",
  "TracingVerbosity": "NormalVerbosity",
  "minSeverity": "Debug",
  "TraceBlockFetchClient": false,
  "TraceBlockFetchDecisions": false,
  "TraceBlockFetchProtocol": false,
  "TraceBlockFetchProtocolSerialised": false,
  "TraceBlockFetchServer": false,
  "TraceChainDb": true,
  "TraceChainSyncBlockServer": false,
  "TraceChainSyncClient": false,
  "TraceChainSyncHeaderServer": false,
  "TraceChainSyncProtocol": false,
  "TraceDNSResolver": true,
  "TraceDNSSubscription": true,
  "TraceErrorPolicy": true,
  "TraceForge": true,
  "TraceHandshake": false,
  "TraceIpSubscription": true,
  "TraceLocalChainSyncProtocol": false,
  "TraceLocalErrorPolicy": true,
  "TraceLocalHandshake": false,
  "TraceLocalTxSubmissionProtocol": false,
  "TraceLocalTxSubmissionServer": false,
  "TraceMempool": true,
  "TraceMux": false,
  "TraceTxInbound": false,
  "TraceTxOutbound": false,
  "TraceTxSubmissionProtocol": false,
  "setupBackends": [
    "KatipBK"
  ],
  "defaultBackends": [
    "KatipBK"
  ],
  "hasEKG": 12788,
  "hasPrometheus": [
    "127.0.0.1",
    12798
  ],
  "setupScribes": [
    {
      "scFormat": "ScText",
      "scKind": "StdoutSK",
      "scName": "stdout",
      "scRotation": null
    }
  ],
  "defaultScribes": [
    [
      "StdoutSK",
      "stdout"
    ]
  ],
  "rotation": {
    "rpKeepFilesNum": 10,
    "rpLogLimitBytes": 5000000,
    "rpMaxAgeHours": 24
    },    

4 Fine grained logging control

It is also possible to have more fine grained control over filtering of trace output, and to match and route trace output to particular backends. This is less efficient than the coarse trace filters above but provides much more precise control. options:

mapBackendsThis routes metrics matching specific names to particular backends. This overrides the defaultBackends listed above. And note that it is an override and not an extension so anything matched here will not go to the default backend, only to the explicitly listed backends.

mapSubtrace This section is more expressive, we are working on its documentation.

  "options": {
    "mapBackends": {
      "cardano.node-metrics": [
        "EKGViewBK",
        {
          "kind": "UserDefinedBK",
          "name": "LiveViewBackend"
        }
      ],
      "cardano.node.BlockFetchDecision.peers": [
        "EKGViewBK",
        {
          "kind": "UserDefinedBK",
          "name": "LiveViewBackend"
        }
      ],
      "cardano.node.ChainDB.metrics": [
        "EKGViewBK",
        {
          "kind": "UserDefinedBK",
          "name": "LiveViewBackend"
        }
      ],
      "cardano.node.metrics": [
        "EKGViewBK",
        {
          "kind": "UserDefinedBK",
          "name": "LiveViewBackend"
        }
      ]
    },
    "mapSubtrace": {
      "benchmark": {
        "contents": [
          "GhcRtsStats",
          "MonotonicClock"
        ],
        "subtrace": "ObservableTrace"
      },
      "#ekgview": {
        "contents": [
          [
            {
              "contents": "cardano.epoch-validation.benchmark",
              "tag": "Contains"
            },
            [
              {
                "contents": ".monoclock.basic.",
                "tag": "Contains"
              }
            ]
          ],
          [
            {
              "contents": "cardano.epoch-validation.benchmark",
              "tag": "Contains"
            },
            [
              {
                "contents": "diff.RTS.cpuNs.timed.",
                "tag": "Contains"
              }
            ]
          ],
          [
            {
              "contents": "#ekgview.#aggregation.cardano.epoch-validation.benchmark",
              "tag": "StartsWith"
            },
            [
              {
                "contents": "diff.RTS.gcNum.timed.",
                "tag": "Contains"
              }
            ]
          ]
        ],
        "subtrace": "FilterTrace"
      },

      "cardano.epoch-validation.utxo-stats": {
        "subtrace": "NoTrace"
      },
      "cardano.node-metrics": {
        "subtrace": "Neutral"
      },
      "cardano.node.metrics": {
        "subtrace": "Neutral"
      }
    }
  }
}