docs: documentation for the experimental etcd feature

This commit is contained in:
Andras Banki-Horvath 2020-06-18 16:47:56 +02:00
parent 3c48cab227
commit fe51f528d1
No known key found for this signature in database
GPG Key ID: 80E5375C094198D8

84
docs/etcd.md Normal file

@ -0,0 +1,84 @@
# Experimental etcd support in LND
With the recent introduction of the `kvdb` interface LND can support multiple
database backends allowing experimentation with the storage model as well as
improving robustness trough eg. replicating essential data.
Building on `kvdb` in v0.11.0 we're adding experimental [etcd](https://etcd.io)
support to LND. As this is an unstable feature heavily in development, it still
has *many* rough edges for the time being. It is therefore highly recommended to
not use LND on `etcd` in any kind of production environment especially not
on bitcoin mainnet.
## Building LND with etcd support
To create a dev build of LND with etcd support use the following command:
```
make tags="kvdb_etcd"
```
The important tag is the `kvdb_etcd`, without which the binary is built without
the etcd driver.
For development it is advised to set the `GOFLAGS` environment variable to
`"-tags=test"` otherwise `gopls` won't work on code in `channeldb/kvdb/etcd`
directory.
## Running a local etcd instance for testing
To start your local etcd instance for testing run:
```
./etcd \
--auto-tls \
--advertise-client-urls=https://127.0.0.1:2379 \
--listen-client-urls=https://0.0.0.0:2379 \
--max-txn-ops=16384 \
--max-request-bytes=104857600
```
The large `max-txn-ops` and `max-request-bytes` values are currently required in
case of running LND with the full graph in etcd. Upcoming versions will split
the database to local and replicated parts and only essential parts will remain
in the replicated database, removing the requirement for these additional
settings. These parameters have been tested to work with testnet LND.
## Configuring LND to run on etcd
To run LND with etcd, additional configuration is needed, specified either
through command line flags or in `lnd.conf`.
Sample command line:
```
./lnd-debug \
--db.backend=etcd \
--db.etcd.host=127.0.0.1:2379 \
--db.etcd.certfile=/home/user/etcd/bin/default.etcd/fixtures/client/cert.pem \
--db.etcd.keyfile=/home/user/etcd/bin/default.etcd/fixtures/client/key.pem \
--db.etcd.insecure_skip_verify
```
Sample `lnd.conf` (with other setting omitted):
```
[db]
backend=etcd
etcd.host=127.0.0.1:2379
etcd.cerfile=/home/user/etcd/bin/default.etcd/fixtures/client/cert.pem
etcd.keyfile=/home/user/etcd/bin/default.etcd/fixtures/client/key.pem
etcd.insecure_skip_verify=true
```
Optionally users can specifiy `db.etcd.user` and `db.etcd.pass` for db user
authentication.
## Migrating existing channel.db to etcd
This is currently not supported.
## Disclaimer
As mentioned before this is an experimental feature, and with that your data
may be lost. Use at your own risk!