Configuration overview

The Lithos client reads one configuration file at startup. This page covers where that file lives, how it inherits the shipped defaults, how to keep secrets out of it, and what the client does when a value is wrong. The pages after it document every setting, grouped by what it controls.

It does not cover installing the client. For that, read the startup guide.

The two files#

The client ships with conf/application.conf, which contains every setting at its default. Do not edit that file. Upgrading replaces it, and any change you made goes with it.

Instead you write your own file, lithos.conf, in lithos-client/bin, and pull in the defaults on its first line:

{
  include file("../conf/application.conf")
 
  # Your settings here override the defaults above.
}

Anything you set after the include overrides the shipped value. Anything you leave out keeps it. The start script passes this file to the client automatically, so there is nothing to point at it.

The format is HOCON↗, which is JSON with comments, unquoted keys and dotted paths. These three are equivalent:

node { url = "http://127.0.0.1" }
node.url = "http://127.0.0.1"
node { url : "http://127.0.0.1" }

Reading the reference pages#

Every setting is listed with the value it ships with and the range the client accepts:

A range is not a recommendation. Most of them are far wider than any sensible value, because their job is to catch a typo or a misplaced decimal point rather than to tune your client. Where a setting has a value worth choosing deliberately, the page says so in prose rather than in the table.

What happens when a value is wrong#

The client validates the whole file before it starts anything, and it reports every problem at once rather than failing on the first one. A run with three mistakes prints three problems, so one editing session fixes all of them:

The client found 2 configuration problems and cannot start safely:
 
  stratum.stratumPort
      70000 is outside 1..65535 (a TCP port)
 
  emission.maxLenderKeys
      64 exceeds node.numAddresses (32). Addresses past index 31 would receive funds this
      client cannot sign for. Raise node.numAddresses to at least 64
 
Fix these in conf/application.conf and restart.

The client then exits. It does not start with a bad value and warn about it.

Three kinds of problem are reported:

• A missing required key. Most settings fall back to a default, but some cannot be guessed and the client refuses to start without them. Each reference page marks these.
• A value of the wrong type, such as text where a number belongs.
• A value outside its range, or one that contradicts another setting.

Some settings are checked against each other#

Most validation looks at one key at a time. The following pairs are not, because a value that is fine alone breaks something when combined:

Keeping secrets out of the file#

lithos.conf holds your node API key and wallet password in plain text. To read them from environment variables instead, add these lines at the end of the file:

  node.key = ${?NODE_KEY_ENV}
  node.pass = ${?NODE_PASS_ENV}
  play.http.secret.key = ${?PLAY_ENV}

The ${?NAME} form overrides the value above it when the variable is set, and is ignored when it is not. That means the file still works unchanged if the variables are missing.

Settings you should change before running#

Four shipped values are placeholders. Three of them are secrets that are published in this documentation, so anyone can reproduce them:

node.storagePath is also empty and has no sensible default, since it is a path on your machine.

The setting groups#

Next steps#

• Node connection and security: the settings every client must have.
• Startup guide: installing and first run.