Browse Source
To give users an idea how the new auto-unlock flag can be used in a more safe way than just writing the password to a file, we add a new wallet management document and describe the unlock feature in detail.master
Oliver Gugger
3 years ago
2 changed files with 226 additions and 26 deletions
@ -0,0 +1,191 @@
|
||||
# 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. |
||||
Loading…
Reference in new issue