configuration.md

description	keywords
This section describes the configuration parameters and their types for your IOTA core node.	IOTA Node Configuration JSON Customize Config reference

Configuration

IOTA core node uses a JSON standard format as a config file. If you are unsure about JSON syntax, you can find more information in the official JSON specs.

You can change the path of the config file by using the -c or --config argument while executing iota-core executable.

For example:

iota-core -c config_example.json

You can always get the most up-to-date description of the config parameters by running:

iota-core -h --full

1. Application

Name	Description	Type	Default value
checkForUpdates	Whether to check for updates of the application or not	boolean	true
shutdown	Configuration for shutdown	object

Shutdown

Name	Description	Type	Default value
stopGracePeriod	The maximum time to wait for background processes to finish during shutdown before terminating the app	string	"5m"
log	Configuration for log	object

Log

Name	Description	Type	Default value
enabled	Whether to store self-shutdown events to a log file	boolean	true
filePath	The file path to the self-shutdown log	string	"shutdown.log"

Example:

  {
    "app": {
      "checkForUpdates": true,
      "shutdown": {
        "stopGracePeriod": "5m",
        "log": {
          "enabled": true,
          "filePath": "shutdown.log"
        }
      }
    }
  }

2. Logger

Name	Description	Type	Default value
name	The optional name of the logger instance. All log messages are prefixed with that name.	string	""
level	The minimum enabled logging level	string	"info"
timeFormat	Sets the logger's timestamp format. (options: "rfc3339", "rfc3339nano", "datetime", "timeonly", and "iso8601")	string	"rfc3339"
outputPaths	A list of file paths or stdout/stderr to write logging output to	array	stdout

Example:

  {
    "logger": {
      "name": "",
      "level": "info",
      "timeFormat": "rfc3339",
      "outputPaths": [
        "stdout"
      ]
    }
  }

3. Peer to Peer

Name	Description	Type	Default value
bindMultiAddresses	The bind multi addresses for p2p connections	array	/ip4/0.0.0.0/tcp/15600 /ip6/::/tcp/15600
connectionManager	Configuration for connectionManager	object
identityPrivateKey	Private key used to derive the node identity (optional)	string	""
identityPrivateKeyFilePath	The file path to the private key used to derive the node identity	string	"testnet/p2p/identity.key"
autopeering	Configuration for autopeering	object

ConnectionManager

Name	Description	Type	Default value
highWatermark	The threshold up on which connections count truncates to the lower watermark	int	10
lowWatermark	The minimum connections count to hold after the high watermark was reached	int	5

Autopeering

Name	Description	Type	Default value
maxPeers	The max number of auto-peer connections. Set to 0 to disable auto-peering.	int	5
bootstrapPeers	Peers to be used as discovery for other peers	array
allowLocalIPs	Allow local IPs to be used for autopeering	boolean	false
externalMultiAddresses	External reacheable multi addresses advertised to the network	array

Example:

  {
    "p2p": {
      "bindMultiAddresses": [
        "/ip4/0.0.0.0/tcp/15600",
        "/ip6/::/tcp/15600"
      ],
      "connectionManager": {
        "highWatermark": 10,
        "lowWatermark": 5
      },
      "identityPrivateKey": "",
      "identityPrivateKeyFilePath": "testnet/p2p/identity.key",
      "autopeering": {
        "maxPeers": 5,
        "bootstrapPeers": [],
        "allowLocalIPs": false,
        "externalMultiAddresses": []
      }
    }
  }

4. Profiling

Name	Description	Type	Default value
enabled	Whether the profiling component is enabled	boolean	false
bindAddress	The bind address on which the profiler listens on	string	"localhost:6060"

Example:

  {
    "profiling": {
      "enabled": false,
      "bindAddress": "localhost:6060"
    }
  }

5. RestAPI

Name	Description	Type	Default value
bindAddress	The bind address on which the REST API listens on	string	"0.0.0.0:14265"
publicRoutes	The HTTP REST routes which can be called without authorization. Wildcards using * are allowed	array	/health /api/routes /api/core/v3/info /api/core/v3/network* /api/core/v3/blocks* /api/core/v3/transactions* /api/core/v3/commitments* /api/core/v3/outputs* /api/core/v3/accounts* /api/core/v3/validators* /api/core/v3/rewards* /api/core/v3/committee* /api/debug/v2/* /api/indexer/v2/* /api/mqtt/v2 /api/blockissuer/v1/*
protectedRoutes	The HTTP REST routes which need to be called with authorization. Wildcards using * are allowed	array	/api/*
debugRequestLoggerEnabled	Whether the debug logging for requests should be enabled	boolean	false
maxPageSize	The maximum number of results per page	uint	100
maxCacheSize	The maximum size of cache for results	string	"50MB"
jwtAuth	Configuration for JWT Auth	object
limits	Configuration for limits	object

JWT Auth

Name	Description	Type	Default value
salt	Salt used inside the JWT tokens for the REST API. Change this to a different value to invalidate JWT tokens not matching this new value	string	"IOTA"

Limits

Name	Description	Type	Default value
maxBodyLength	The maximum number of characters that the body of an API call may contain	string	"1M"
maxResults	The maximum number of results that may be returned by an endpoint	int	1000

Example:

  {
    "restAPI": {
      "bindAddress": "0.0.0.0:14265",
      "publicRoutes": [
        "/health",
        "/api/routes",
        "/api/core/v3/info",
        "/api/core/v3/network*",
        "/api/core/v3/blocks*",
        "/api/core/v3/transactions*",
        "/api/core/v3/commitments*",
        "/api/core/v3/outputs*",
        "/api/core/v3/accounts*",
        "/api/core/v3/validators*",
        "/api/core/v3/rewards*",
        "/api/core/v3/committee*",
        "/api/debug/v2/*",
        "/api/indexer/v2/*",
        "/api/mqtt/v2",
        "/api/blockissuer/v1/*"
      ],
      "protectedRoutes": [
        "/api/*"
      ],
      "debugRequestLoggerEnabled": false,
      "maxPageSize": 100,
      "maxCacheSize": "50MB",
      "jwtAuth": {
        "salt": "IOTA"
      },
      "limits": {
        "maxBodyLength": "1M",
        "maxResults": 1000
      }
    }
  }

6. DebugAPI

Name	Description	Type	Default value
enabled	Whether the DebugAPI component is enabled	boolean	false
db	Configuration for Database	object

Database

Name	Description	Type	Default value
path	The path to the database folder	string	"testnet/debug"
maxOpenDBs	Maximum number of open database instances	int	2
granularity	How many slots should be contained in a single DB instance	int	100
pruning	Configuration for pruning	object

Pruning

Name	Description	Type	Default value
threshold	How many epochs should be retained	uint	1

Example:

  {
    "debugAPI": {
      "enabled": false,
      "db": {
        "path": "testnet/debug",
        "maxOpenDBs": 2,
        "granularity": 100,
        "pruning": {
          "threshold": 1
        }
      }
    }
  }

7. MetricsTracker

Name	Description	Type	Default value
enabled	Whether the Metrics Tracker plugin is enabled	boolean	true

Example:

  {
    "metricsTracker": {
      "enabled": true
    }
  }

8. Database

Name	Description	Type	Default value
engine	The used database engine (rocksdb/mapdb)	string	"rocksdb"
path	The path to the database folder	string	"testnet/database"
maxOpenDBs	Maximum number of open database instances	int	5
pruning	Configuration for pruning	object

Pruning

Name	Description	Type	Default value
threshold	How many finalized epochs should be retained	uint	30
size	Configuration for size	object

Size

Name	Description	Type	Default value
enabled	Whether to delete old block data from the database based on maximum database size	boolean	true
targetSize	Target size of the database	string	"30GB"
reductionPercentage	The percentage the database size gets reduced if the target size is reached	float	10.0
cooldownTime	Cooldown time between two pruning by database size events	string	"5m"

Example:

  {
    "db": {
      "engine": "rocksdb",
      "path": "testnet/database",
      "maxOpenDBs": 5,
      "pruning": {
        "threshold": 30,
        "size": {
          "enabled": true,
          "targetSize": "30GB",
          "reductionPercentage": 10,
          "cooldownTime": "5m"
        }
      }
    }
  }

9. Protocol

Name	Description	Type	Default value
snapshot	Configuration for snapshot	object
commitmentCheck	Specifies whether commitment and ledger checks should be enabled	boolean	true
filter	Configuration for filter	object
protocolParametersPath	The path of the protocol parameters file	string	"testnet/protocol_parameters.json"
baseToken	Configuration for baseToken	object

Snapshot

Name	Description	Type	Default value
path	The path of the snapshot file	string	"testnet/snapshot.bin"
depth	Defines how many slot diffs are stored in the snapshot, starting from the full ledgerstate	int	5

Filter

Name	Description	Type	Default value
maxAllowedClockDrift	The maximum drift our wall clock can have to future blocks being received from the network	string	"5s"

BaseToken

Name	Description	Type	Default value
name	The base token name	string	"Shimmer"
tickerSymbol	The base token ticker symbol	string	"SMR"
unit	The base token unit	string	"SMR"
subunit	The base token subunit	string	"glow"
decimals	The base token amount of decimals	uint	6

Example:

  {
    "protocol": {
      "snapshot": {
        "path": "testnet/snapshot.bin",
        "depth": 5
      },
      "commitmentCheck": true,
      "filter": {
        "maxAllowedClockDrift": "5s"
      },
      "protocolParametersPath": "testnet/protocol_parameters.json",
      "baseToken": {
        "name": "Shimmer",
        "tickerSymbol": "SMR",
        "unit": "SMR",
        "subunit": "glow",
        "decimals": 6
      }
    }
  }

10. Retainer

Name	Description	Type	Default value
debugStoreErrorMessages	Whether to store debug error messages in the database	boolean	false

Example:

  {
    "retainer": {
      "debugStoreErrorMessages": false
    }
  }

11. Node

Name	Description	Type	Default value
alias	Set an alias to identify a node	string	"IOTA-Core node"

Example:

  {
    "node": {
      "alias": "IOTA-Core node"
    }
  }

12. Prometheus

Name	Description	Type	Default value
enabled	Whether the Metrics component is enabled	boolean	true
bindAddress	Bind address on which the Prometheus exporter server	string	"0.0.0.0:9311"
goMetrics	Include go metrics	boolean	false
processMetrics	Include process metrics	boolean	false
promhttpMetrics	Include promhttp metrics	boolean	false

Example:

  {
    "prometheus": {
      "enabled": true,
      "bindAddress": "0.0.0.0:9311",
      "goMetrics": false,
      "processMetrics": false,
      "promhttpMetrics": false
    }
  }

13. INX

Name	Description	Type	Default value
enabled	Whether the INX plugin is enabled	boolean	false
bindAddress	The bind address on which the INX can be accessed from	string	"localhost:9029"

Example:

  {
    "inx": {
      "enabled": false,
      "bindAddress": "localhost:9029"
    }
  }