mirrors/electrs
1
0
Fork 0
mirror of https://github.com/romanz/electrs.git synced 2025-02-23 14:50:45 +01:00
Code Issues Projects Releases Wiki Activity

Improve documentation

Browse source 
This improves documentation of configuration based on @BTCBellyButton
suggestions in #344. It contains a few more tweaks.
This commit is contained in:
Martin Habovstiak 2021-02-01 22:33:04 +01:00
parent 8fb4d7c286
commit 8ca4f7ae7f
1 changed files with 20 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
doc/usage.md
View file

@ -174,16 +174,30 @@ Electrs can be configured using command line, environment variables and configur
### Configuration files and priorities
The config files must be in the Toml format.
If you've never seen a Toml configuration file, there's an [example configuration file](config_example.toml) available.
The Toml-formatted config files ([an example here](config_example.toml)) are (from lowest priority to highest): `/etc/electrs/config.toml`, `~/.electrs/config.toml`, `./electrs.toml`.
The config files are (from lowest priority to highest): `/etc/electrs/config.toml`, `~/.electrs/config.toml`, `./electrs.toml`.
The options in highest-priority config files override options set in lowest-priority config files.
The options in highest-priority config files override options set in lowest-priority config files. Environment variables override options in config files and finally arguments override everythig else. There are two special arguments `--conf` which reads the specified file and `--conf-dir`, which read all the files in the specified directory. The options in those files override **everything that was set previously, including arguments that were passed before these arguments**. In general, later arguments override previous ones. It is a good practice to use these special arguments at the beginning of the command line in order to avoid confusion.
**Environment variables** override options in config files and finally **arguments** override everythig else.
For each command line argument an environment variable of the same name with `ELECTRS_` prefix, upper case letters and underscores instead of hypens exists (e.g. you can use `ELECTRS_ELECTRUM_RPC_ADDR` instead of `--electrum-rpc-addr`). Similarly, for each such argument an option in config file exists with underscores instead of hypens (e.g. `electrum_rpc_addr`). In addition, config files support `cookie` option to specify cookie - this is not available using command line or environment variables for security reasons (other applications could read it otherwise). Note that this is different from using `cookie_path`, which points to a file containing the cookie instead of being the cookie itself.
There are two special arguments `--conf` which reads the specified file and `--conf-dir`, which read all the files in the specified directory.
Finally, you need to use a number in config file if you want to increase verbosity (e.g. `verbose = 3` is equivalent to `-vvv`) and `true` value in case of flags (e.g. `timestamp = true`)
The options in those files override **everything** that was set previously, **including arguments** that were passed before these two special arguments.
In general, later arguments override previous ones. It is a good practice to use these special arguments at the beginning of the command line in order to avoid confusion.
**Naming convention**
For each command line argument an **environment variable** of the same name with `ELECTRS_` prefix, upper case letters and underscores instead of hypens exists (e.g. you can use `ELECTRS_ELECTRUM_RPC_ADDR` instead of `--electrum-rpc-addr`).
Similarly, for each such argument an option in config file exists with underscores instead of hypens (e.g. `electrum_rpc_addr`).
You need to use a number in config file if you want to increase verbosity (e.g. `verbose = 3` is equivalent to `-vvv`) and `true` value in case of flags (e.g. `timestamp = true`)
**Authentication**
In addition, config files support `cookie` option (warning: it will be renamed in near future!) to specify username and password - this is not available using command line or environment variables for security reasons (other applications could read it otherwise).
**Important note**: `cookie` is different from `cookie_file`, which points to a file containing the cookie instead of being the cookie itself!
If you are using `-rpcuser=USER` and `-rpcpassword=PASSWORD` of `bitcoind` for authentication, please use `cookie="USER:PASSWORD"` option in one of the [config files](https://github.com/romanz/electrs/blob/master/doc/usage.md#configuration-files-and-priorities).
Otherwise, [`~/.bitcoin/.cookie`](https://github.com/bitcoin/bitcoin/blob/0212187fc624ea4a02fc99bc57ebd413499a9ee1/contrib/debian/examples/bitcoin.conf#L70-L72) will be used as the default cookie file, allowing this server to use bitcoind JSONRPC interface.