lnd.xprv/docs/wallet.md

192 lines
6.9 KiB
Markdown
Raw Normal View History

# Wallet management
The wallet in the context of `lnd` is a database file (located in the data
directory, for example `~/.lnd/data/chain/bitcoin/mainnet/wallet.db` on Linux)
that contains all addresses and private keys for the on-chain **and** off-chain
(LN) funds.
The wallet is independent of the chain backend that is used (`bitcoind`, `btcd`
or `neutrino`) and must therefore be created as the first step after starting
up a fresh `lnd` node.
To protect the sensitive content of the wallet, the database is encrypted with
a password chosen by the user when creating the wallet (simply called "wallet
password"). `lnd` will not store that password anywhere by itself (as that would
defeat the purpose of the password) so every time `lnd` is restarted, its wallet
needs to be unlocked with that password. This can either be done [manually
through the command line](#unlocking-a-wallet) or (starting with `lnd` version
`v0.13.0-beta`) [automatically from a file](#auto-unlocking-a-wallet).
## Creating a wallet
If `lnd` is being run for the first time, create a new wallet with:
```shell
⛰ lncli create
```
This will prompt for a wallet password, and optionally a cipher seed
passphrase.
`lnd` will then print a 24 word cipher seed mnemonic, which can be used to
recover the wallet in case of data loss. The user should write this down and
keep in a safe place.
In case a node needs to be recovered from an existing seed, this can also be
done through the `create` command. Please refer to the
[recovery guide](recovery.md) for more information about recovering a node.
## Unlocking a wallet
Every time `lnd` starts up fresh (e.g. after a system restart or a version
upgrade) the user-chosen wallet password needs to be entered to unlock (decrypt)
the wallet database.
This will be indicated in `lnd`'s log with a message like this:
```text
2021-05-06 11:36:11.445 [INF] LTND: Waiting for wallet encryption password. Use `lncli create` to create a wallet, `lncli unlock` to unlock an existing wallet, or `lncli changepassword` to change the password of an existing wallet and unlock it.
```
Unlocking the password manually is as simple as running the command
```shell
⛰ lncli unlock
```
and then typing the wallet password.
## Auto-unlocking a wallet
In some situations (for example automated, cluster based setups) it can be
impractical to manually unlock the wallet every time `lnd` is restarted.
In `lnd` version `v0.13.0-beta` and later there is a configuration option to
tell the wallet to auto-unlock itself by reading the password from a file. This
can only be activated _after_ the wallet was created manually.
### Very basic example (not very secure)
This example only tries to give a basic, minimal example on how to use the
auto-unlock feature. Storing a password in a file on the same disk as the wallet
database is not in itself more secure than leaving the database unencrypted in
the first place. This example might be useful in a containerized environment
though where the secrets are mounted to a file anyway.
- Start `lnd` without the flag:
```shell
⛰ lnd --bitcoin.active --bitcoin.xxxx .....
```
- Create the wallet and write down the seed in a safe place:
```shell
⛰ lncli create
```
- Stop `lnd` again:
```shell
⛰ lncli stop
```
- Write the password to a file:
```shell
⛰ echo 'my-$up3r-Secret-Passw0rd' > /some/safe/location/password.txt
```
- Make sure the password file can only be read by our user:
```shell
⛰ chmod 0400 /some/safe/location/password.txt
```
- Start `lnd` with the auto-unlock flag:
```shell
⛰ lnd --bitcoin.active --bitcoin.xxxx ..... \
--wallet-unlock-password-file=/some/safe/location/password.txt
```
As with every command line flag, the `wallet-unlock-password-file` option can
also be added to `lnd`'s configuration file, for example:
```text
[Application Options]
debuglevel=debug
wallet-unlock-password-file=/some/safe/location/password.txt
[Bitcoin]
bitcoin.active=1
...
```
### More secure example with password manager and using a named pipe
This example is a bit more involved and requires the use of a password manager
of some sort. It will also only work on Unix like file systems that support
named pipes.
We will use the password manager [`pass`](https://www.passwordstore.org/) as an
example here but it should work similarly with other password managers.
- Start `lnd` without the flag:
```shell
⛰ lnd --bitcoin.active --bitcoin.xxxx .....
```
- Create the wallet and write down the seed in a safe place:
```shell
⛰ lncli create
```
- Stop `lnd` again:
```shell
⛰ lncli stop
```
- Store the password in `pass`:
```shell
⛰ pass insert lnd/my-wallet-password
```
- Create a startup script for starting `lnd`, for example `run-lnd.sh`:
```shell
#!/bin/bash
# Create a named pipe. As the name suggests, this is a FIFO (first in first
# out) pipe. Everything sent in can be read out again without the content
# actually being written to a disk.
mkfifo /tmp/wallet-password-pipe
# Read the password from the manager and attempt to write it to the pipe. Any
# write to a pipe will only be accepted once there is a process that reads
# from the pipe at the same time. That's why we need to run this process in
# the background (the ampersand & at the end) because it would block our
# script from continuing otherwise.
pass lnd/my-wallet-password > /tmp/wallet-password-pipe &
# Now we can start lnd.
lnd --bitcoin.active --bitcoin.xxxx ..... \
--wallet-unlock-password-file=/tmp/wallet-password-pipe
```
- Run the startup script instead of running `lnd` directly.
```shell
⛰ ./run-lnd.sh
```
## Changing the password
Changing the wallet password is possible but only while the wallet is locked.
So after restarting `lnd`, instead of using the `unlock` command, the
`changepassword` command can be used:
```shell
⛰ lncli changepassword
```
This will ask for the old/existing password and a new one. If successful, the
database is re-encrypted with the new password and then the wallet is also
unlocked in the process.
## DO NOT USE --noseedbackup on mainnet
There is a way to get rid of the need to unlock the wallet password: The
`--noseedbackup` flag.
Using that flag with **real funds (mainnet) is extremely risky for two reasons**:
1. On first startup a wallet is created automatically. The seed phrase (the 24
words needed to restore a wallet) is never shown to the user. Therefore if
the worst thing happens and the hard disk crashes or the wallet file is
deleted by accident, **THERE IS NO WAY OF GETTING THE FUNDS BACK**.
2. In addition to the seed not being known to the user, the wallet database is
also not protected. A well-known default password is chosen for the
encryption. Any user (or malware) with access to the wallet database can
steal the funds if they copy the file.
The `--noseedbackup` flag should only ever be used in a test setup, for example
on Bitcoin testnet, regtest or simnet.