Configuring Iroha

WORK IN PROGRESS

It is not implemented yet. Early draft document according to the RFC.

When running iroha from the command line, Iroha will try to resolve a config file named iroha.toml inside the current working directory. Then it tries to read a set of Environment Variables associated with configuration parameters. The most basic iroha.toml config file looks like this:

public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9"
private_key = { digest = "ed25519", payload = "82886B5A2BB3785F3CA8F8A78F60EA9DB62F939937B1CFA8407316EF07909A8D236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" }

# Peer-to-Peer communication address
address = "localhost:1337"

[genesis]
public_key = "..."

[torii]
# API address
address = "localhost:8080"

The path to the configuration file can be overwritten either with --config CLI argument, or with IROHA_CONFIG environment variable:

Using CLI

$ iroha --config ./config.toml

Using ENV

$ IROHA_CONFIG=/path/to/config.toml iroha

Additionally, Iroha reads a set of Environment Variables, associated with configuration parameters. Values from ENV override values from the config file. For example:

ENV variables

PUBLIC_KEY=ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9
PRIVATE_KEY="{\"digest\":\"ed25519\",\"payload\":\"82886B5A2BB3785F3CA8F8A78F60EA9DB62F939937B1CFA8407316EF07909A8D236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B\"}"
NETWORK_ADDRESS=localhost:1337
TORII_API_ADDRESS=localhost:8080

Equivalent in TOML

public_key = "ed0120FAFCB2B27444221717F6FCBF900D5BE95273B1B0904B08C736B32A19F16AC1F9"
private_key = { digest = "ed25519", payload = "82886B5A2BB3785F3CA8F8A78F60EA9DB62F939937B1CFA8407316EF07909A8D236808A6D4C12C91CA19E54686C2B8F5F3A786278E3824B4571EF234DEC8683B" }
address = "localhost:1337"

[torii]
api_address = "localhost:8080"

Please refer to each field's documentation for specific ENV names.

Debugging

To trace how configuration is resolved, run iroha with --trace-config flag:

$ iroha --trace-config

The output will be something like:

TODO: sample output

TODO: maybe also enable with IROHA_CONFIG_TRACE=1 env var?

TOML Format

Iroha uses the TOML (Tom's Obvious Minimal Language) format for its configuration. Please refer to its documentation if you need assistance with how it works.

Required Parameters

• public_key: explain the option
• private_key: explain the option
• address: explain the option
• genesis.public_key: explain the option
• genesis.private_key if the peer is the one who submits the genesis. explain the option
• sumeragi.trusted_peers: explain the option. It is not strictly required, but you might need to set it in most cases.
• torii.address: explain the option

Modules Overview

TODO: list each section (sumeragi, torii, kura etc) with links and short explanations of their responsibility.

• Base Options: explain
• Genesis: explain
• Sumeragi: explain
• Torii: explain
• Queue: explain
• Kura: explain
• Logger: explain
• Telemetry: explain
• Snapshot

---

TODO:

• Consider refining Number types to exact Integer, Float, Unsigned 64-bits integer?
• Is sumeragi.trusted_peers optional or required?
• Define more ENVs, and provide samples of how it should be parsed