Configuration

While iroh is primarily a library it also supplies a CLI which is useful for exploring various parts of iroh. The iroh CLI uses persistent node storage and also supports a configuration file. Below are the details of where these are located and how they are used.

When using iroh as a library, check the documenetation of the library to see what the defaults are.

Ports

An iroh node binds to two ports by default:

Data Directory

By default the iroh CLI persists to a data directory that keeps any data that should be kept across restarts. The location of that directory is platform specific:

If the IROH_DATA_DIR environment variable is set, all other values will be ignored in favour of IROH_DATA_DIR. If the directory path does not exist, iroh will attempt to create all directories in the path string (similar to mkdir -p on Unix systems), failing if the final path cannot be written to.

Log files

By default iroh will create log files in $IROH_DATA_DIR/logs, named iroh.YYYY-MM-DD-HH.log.

Configuration file

The configuration directory also has a platform-specific default value:

If the IROH_CONFIG_DIR environment variable is set, all other values will be ignored in favour of IROH_CONFIG_DIR.

The iroh CLI loads configuration from the $IROH_CONFIG_DIR/iroh.config.toml file. The file is in TOML format, and all values are optional, including the file itself.

Iroh does not create iroh.config.toml by default.

Relay nodes

Relay nodes are used to assist in holepunching and are identified by their url. They assist in establishing connections. Number0 currently runs two relay nodes, one in North America and one in Europe.

To change the relay servers used, for example when running your own relay server, they can be configured in the configuration file.

This is what the default configuration for the Relay nodes would look like:

[[relay_nodes]]
url = "https://use1-1.derp.iroh.network."
stun_only = false
stun_port = 3478

[[relay_nodes]]
url = "https://euw1-1.derp.iroh.network."
stun_only = false
stun_port = 3478

[[relay_nodes]]
url = "https://aps1-1.relay.iroh.network."
stun_only = false
stun_port = 3478

GC Policy

The blob store needs to run garbage collection to remove unused blobs. This allows configuring garbage collection:

[gc_policy]
enabled = true
interval = 300

Here interval is the interval in seconds after which GC cycles will run. If enabled is false GC is disabled and the interval ignored.

Metrics collection

The iroh node can have a Prometheus metrics server. This is enabled by configuring the address on which metrics should be served:

metrics_addr = "127.0.0.1:9090"

File logging

By default log files are created in $IROH_DATA_DIR/logs/ and are rotated once per hour using the filename patter of iroh.YYYY-MM-DD-HH.log. This can also be customised in the configuration file however:

[file_logging]
rust_log = "debug"
max_files = 4
rotation = "hourly"
dir = "/path/to/data/dir/logs/"

• The rust_log field can be used to customize the tracing-subscriber EnvFilter. All logs matching this filter will be recorded in the logfile.

• The max_files field configures how many old log files should be kept. If there are more log files the oldes ones will be deleted.

• The rotation field configurs how often the logfile is rotated and a new logfile created:

  • hourly creates a new file every hour.
  • daily creates a new file once a day.
  • never will never create a new logfile.

• The dir field allows changing the directory in which the logfiles are created. This field can not contain any special shell expansion characters or environment variables, it must be a full path name.

Additionally tracing-subscriber EnvFilter can also be specified using an environment variable. The IROH_FILE_RUST_LOG environment variable will override the file_logging.rust_log field.

Full example

The full default configuration would more or less be specified as:

metrics_addr = "127.0.0.1:9090"

[[relay_nodes]]
url = "https://use1-1.derp.iroh.network."
stun_only = false
stun_port = 3478

[[relay_nodes]]
url = "https://euw1-1.derp.iroh.network."
stun_only = false
stun_port = 3478

[[relay_nodes]]
url = "https://aps1-1.relay.iroh.network."
stun_only = false
stun_port = 3478

[gc_policy]
enabled = false

[file_logging]
rust_log = "debug"
max_files = 4
rotation = "hourly"

# The default directory for the log files can not be
# expressed here since environment variables can not
# be used and the location varies by platform.
# Omitting # it will result in the default being used.
#dir = "$IROH_DATA_DIR/logs/"

Environment Variables

The Following is a full list of environment variables the iroh CLI will use:

• IROH_CONFIG_DIR

  The location where the configuration file will be loaded from.

• IROH_DATA_DIR

  The location where iroh will store all state by default. Including the log files.

• IROH_FILE_RUST_LOG

  Overrides the tracing-subscriber EnvFilter used for the log file, see above.

• IROH_AUTHOR

  The default document author to use.

• IROH_DOC

  The default document to use.