You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The wallet in the context of `lnd` is a database file (located in the data
4
-
directory, for example `~/.lnd/data/chain/bitcoin/mainnet/wallet.db` on Linux)
5
-
that contains all addresses and private keys for the on-chain **and** off-chain
6
-
(LN) funds.
3
+
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.
7
4
8
-
The wallet is independent of the chain backend that is used (`bitcoind`, `btcd`
9
-
or `neutrino`) and must therefore be created as the first step after starting
10
-
up a fresh `lnd` node.
5
+
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.
11
6
12
-
To protect the sensitive content of the wallet, the database is encrypted with
13
-
a password chosen by the user when creating the wallet (simply called "wallet
14
-
password"). `lnd` will not store that password anywhere by itself (as that would
15
-
defeat the purpose of the password) so every time `lnd` is restarted, its wallet
16
-
needs to be unlocked with that password. This can either be done [manually
17
-
through the command line](#unlocking-a-wallet) or (starting with `lnd` version
18
-
`v0.13.0-beta`) [automatically from a file](#auto-unlocking-a-wallet).
7
+
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](wallet.md#unlocking-a-wallet) or (starting with `lnd` version `v0.13.0-beta`) [automatically from a file](wallet.md#auto-unlocking-a-wallet).
19
8
20
9
## Creating a wallet
21
10
22
11
If `lnd` is being run for the first time, create a new wallet with:
12
+
23
13
```shell
24
14
$ lncli create
25
15
```
26
-
This will prompt for a wallet password, and optionally a cipher seed
27
-
passphrase.
28
16
29
-
`lnd` will then print a 24 word cipher seed mnemonic, which can be used to
30
-
recover the wallet in case of data loss. The user should write this down and
31
-
keep in a safe place.
17
+
This will prompt for a wallet password, and optionally a cipher seed passphrase.
18
+
19
+
`lnd` will then print a 24 word cipher seed mnemonic.
32
20
33
-
In case a node needs to be recovered from an existing seed, this can also be
34
-
done through the `create` command. Please refer to the
35
-
[recovery guide](recovery.md) for more information about recovering a node.
21
+
{% hint style="warning" %}
22
+
Write down your 24 word cipher seed mnemonic, ideally by hand with pencil on paper. Keep the seed in a safe place.
23
+
{% endhint %}
24
+
25
+
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.
36
26
37
27
## Unlocking a wallet
38
28
39
-
Every time `lnd` starts up fresh (e.g. after a system restart or a version
40
-
upgrade) the user-chosen wallet password needs to be entered to unlock (decrypt)
41
-
the wallet database.
29
+
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.
42
30
43
31
This will be indicated in `lnd`'s log with a message like this:
44
32
45
-
```text
33
+
```
46
34
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.
47
35
```
48
36
49
37
Unlocking the password manually is as simple as running the command
38
+
50
39
```shell
51
40
$ lncli unlock
52
41
```
42
+
53
43
and then typing the wallet password.
54
44
55
45
## Auto-unlocking a wallet
56
46
57
-
In some situations (for example automated, cluster based setups) it can be
58
-
impractical to manually unlock the wallet every time `lnd` is restarted.
47
+
In some situations (for example automated, cluster based setups) it can be impractical to manually unlock the wallet every time `lnd` is restarted.
59
48
60
-
In `lnd` version `v0.13.0-beta` and later there is a configuration option to
61
-
tell the wallet to auto-unlock itself by reading the password from a file. This
62
-
can only be activated _after_ the wallet was created manually.
49
+
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.
63
50
64
51
### Very basic example (not very secure)
65
52
66
-
This example only tries to give a basic, minimal example on how to use the
67
-
auto-unlock feature. Storing a password in a file on the same disk as the wallet
68
-
database is not in itself more secure than leaving the database unencrypted in
69
-
the first place. This example might be useful in a containerized environment
70
-
though where the secrets are mounted to a file anyway.
71
-
72
-
- Start `lnd` without the flag:
73
-
```shell
74
-
$ lnd --bitcoin.active --bitcoin.xxxx .....
75
-
```
76
-
- Create the wallet and write down the seed in a safe place:
As with every command line flag, the `wallet-unlock-password-file` option can
99
-
also be added to `lnd`'s configuration file, for example:
100
-
101
-
```text
53
+
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.
54
+
55
+
* Start `lnd` without the flag:
56
+
57
+
```shell
58
+
$ lnd --bitcoin.active --bitcoin.xxxx .....
59
+
```
60
+
* Create the wallet and write down the seed in a safe place:
- Run the startup script instead of running `lnd` directly.
157
-
```shell
158
-
$ ./run-lnd.sh
159
-
```
101
+
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.
102
+
103
+
We will use the password manager [`pass`](https://www.passwordstore.org/) as an example here, but it should work similarly with other password managers.
104
+
105
+
* Start `lnd` without the flag:
106
+
107
+
```shell
108
+
$ lnd --bitcoin.active --bitcoin.xxxx .....
109
+
```
110
+
* Create the wallet and write down the seed in a safe place:
111
+
112
+
```shell
113
+
$ lncli create
114
+
```
115
+
* Stop `lnd` again:
116
+
117
+
```shell
118
+
$ lncli stop
119
+
```
120
+
* Store the password in `pass`:
121
+
122
+
```shell
123
+
$ pass insert lnd/my-wallet-password
124
+
```
125
+
* Create a startup script for starting `lnd`, for example `run-lnd.sh`:
126
+
127
+
```shell
128
+
#!/bin/bash
129
+
130
+
# Create a named pipe. As the name suggests, this is a FIFO (first in first
131
+
# out) pipe. Everything sent in can be read out again without the content
132
+
# actually being written to a disk.
133
+
mkfifo /tmp/wallet-password-pipe
134
+
135
+
# Read the password from the manager and attempt to write it to the pipe. Any
136
+
# write to a pipe will only be accepted once there is a process that reads
137
+
# from the pipe at the same time. That's why we need to run this process in
138
+
# the background (the ampersand & at the end) because it would block our
* Run the startup script instead of running `lnd` directly.
147
+
148
+
```shell
149
+
$ ./run-lnd.sh
150
+
```
160
151
161
152
## Changing the password
162
153
163
-
Changing the wallet password is possible but only while the wallet is locked.
164
-
So after restarting `lnd`, instead of using the `unlock` command, the
165
-
`changepassword` command can be used:
154
+
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:
166
155
167
156
```shell
168
157
$ lncli changepassword
169
158
```
170
159
171
-
This will ask for the old/existing password and a new one. If successful, the
172
-
database is re-encrypted with the new password and then the wallet is also
173
-
unlocked in the process.
160
+
This will ask forthe old/existing password and a new one. If successful, the database is re-encrypted with the new password and then the wallet is also unlockedin the process.
174
161
175
-
## DO NOT USE --noseedbackup on mainnet
162
+
{% hint style="danger" %}
163
+
## DO NOT USE `--noseedbackup` on mainnet
164
+
{% endhint %}
176
165
177
-
There is a way to get rid of the need to unlock the wallet password: The
178
-
`--noseedbackup` flag.
166
+
There is a way to get rid of the need to unlock the wallet password: The `--noseedbackup` flag.
179
167
180
168
Using that flag with **real funds (mainnet) is extremely risky for two reasons**:
181
-
1. On first startup a wallet is created automatically. The seed phrase (the 24
182
-
words needed to restore a wallet) is never shown to the user. Therefore, if
183
-
the worst thing happens and the hard disk crashes or the wallet file is
184
-
deleted by accident, **THERE IS NO WAY OF GETTING THE FUNDS BACK**.
185
-
2. In addition to the seed not being known to the user, the wallet database is
186
-
also not protected. A well-known default password is chosen for the
187
-
encryption. Any user (or malware) with access to the wallet database can
188
-
steal the funds if they copy the file.
189
-
190
-
The `--noseedbackup` flag should only ever be used in a test setup, for example
191
-
on Bitcoin testnet, regtest or simnet.
169
+
170
+
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**.
171
+
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.
172
+
173
+
The `--noseedbackup` flag should only ever be used in a test setup, for example on Bitcoin testnet, regtest or simnet.
0 commit comments