forked from ElementsProject/lightning
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlightningd-config.5.txt
376 lines (285 loc) · 13.6 KB
/
lightningd-config.5.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
LIGHTNINGD-CONFIG(5)
====================
:doctype: manpage
NAME
----
lightningd-config - Lightning daemon configuration file
SYNOPSIS
--------
*~/.lightning/config*
DESCRIPTION
-----------
When lightningd(8) starts up, it reads a configuration file. By
default that is 'config' in the *.lightning* subdirectory of the home
directory (if it exists), but that can be changes by the
'--lightning-dir' or '--conf' options on the lightningd(8) command
line.
Configuration file options are processed first, then command line
options: later options override earlier ones except 'addr' options
which accumulate.
All these options are mirrored as commandline arguments to
lightningd(8), so '--foo' becomes simply 'foo' in the configuration
file, and '--foo=bar' becomes 'foo=bar' in the configuration file.
Blank lines and lines beginning with '#' are ignored.
DEBUGGING
---------
'--help' will show you the defaults for many options; they vary with
network settings so you can specify '--network' before '--help' to see
the defaults for that network.
The lightning-listconfigs(7) command will output a valid configuration
file using the current settings.
OPTIONS
-------
General options
~~~~~~~~~~~~~~~
*allow-deprecated-apis*='BOOL'::
Enable deprecated options, JSONRPC commands, fields, etc. It
defaults to 'true', but you should set it to 'false' when testing
to ensure that an upgrade won't break your configuration.
*help*::
Print help and exit. Not very useful inside a configuration file, but
fun to put in other's config files while their computer is unattended.
*version*::
Print version and exit. Also useless inside a configuration file,
but putting this in someone's config file may convince them to
read this man page.
Bitcoin control options:
*network*='NETWORK'::
Select the network parameters ('bitcoin', 'testnet', or 'regtest').
*testnet*::
Alias for 'network=testnet'.
*signet*::
Alias for 'network=signet'.
*mainnet*::
Alias for 'network=bitcoin'.
*bitcoin-cli*='PATH'::
The name of 'bitcoin-cli' executable to run.
*bitcoin-datadir*='DIR'::
'-datadir' argument to supply to bitcoin-cli(1).
*bitcoin-rpcuser*='USER'::
The RPC username for talking to bitcoind(1).
*bitcoin-rpcpassword*='PASSWORD'::
The RPC password for talking to bitcoind(1).
*bitcoin-rpcconnect*='HOST'::
The bitcoind(1) RPC host to connect to.
*bitcoin-rpcport*='PORT'::
The bitcoind(1) RPC port to connect to.
*bitcoin-retry-timeout*='SECONDS'::
Number of seconds to keep trying a bitcoin-cli(1) command.
If the command keeps failing after this time, exit with a
fatal error.
*rescan*='BLOCKS'::
Number of blocks to rescan from the current head, or absolute blockheight
if negative. This is only needed if something goes badly wrong.
Lightning daemon options
~~~~~~~~~~~~~~~~~~~~~~~~
*lightning-dir*='DIR'::
Sets the working directory. All files (except '--conf' on the command
line) are relative to this.
*pid-file*='PATH'::
Specify pid file to write to.
*log-level*='LEVEL'::
What log level to print out: options are io, debug, info, unusual, broken.
*log-prefix*='PREFIX'::
Prefix for log lines: this can be customized if you want to merge logs with
multiple daemons.
*log-file*='PATH'::
Log to this file instead of stdout. Sending lightningd(1) SIGHUP will cause
it to reopen this file (useful for log rotation).
*rpc-file*='PATH'::
Set JSON-RPC socket (or /dev/tty), such as for lightning-cli(1).
*daemon*::
Run in the background, suppress stdout and stderr.
*conf*='PATH'::
Sets configuration file (default: *lightning-dir*/'config' ). If this is
a relative path, it is relative to the starting directory, not
*lightning-dir* (unlike other paths). 'PATH' must exist and be readable
(we allow missing files in the default case).
Using this inside a configuration file is meaningless.
Lightning node customization options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*rgb*='RRGGBB'::
Your favorite color as a hex code.
*alias*='NAME'::
Up to 32 UTF-8 characters to tag your node. Completely silly, since anyone
can call their node anything they want. The default is an
NSA-style codename derived from your public key, but "Peter Todd"
and "VAULTERO" are good options, too.
*fee-base*='MILLISATOSHI'::
Default: 1000. The base fee to charge for every payment which passes
through. Note that millisatoshis are a very, very small unit!
Changing this value will only affect new channels and not existing ones.
If you want to change fees for existing channels, use the RPC call
lightningd-setchannelfee(7).
*fee-per-satoshi*='MILLIONTHS'::
Default: 10 (0.001%). This is the proportional fee to charge for every
payment which passes through. As percentages are too coarse, it's in
millionths, so 10000 is 1%, 1000 is 0.1%. Changing this value will only
affect new channels and not existing ones. If you want to change fees for
existing channels, use the RPC call lightningd-setchannelfee(7).
*min-capacity-sat*='SATOSHI'::
Default: 10000. This value defines the minimal effective channel capacity
in satoshi to accept for channel opening requests. If a peer tries to open
a channel smaller than this, the opening will be rejected.
*ignore-fee-limits*='BOOL'::
Allow nodes which establish channels to us to set any fee they
want. This may result in a channel which cannot be closed, should
fees increase, but make channels far more reliable since we never
close it due to unreasonable fees.
*commit-time*='MILLISECONDS::
How long to wait before sending commitment messages to the peer: in
theory increasing this would reduce load, but your node would have to be
extremely busy node for you to even notice.
Lightning channel and HTLC options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*watchtime-blocks*='BLOCKS'::
How long we need to spot an outdated close attempt: on opening a channel
we tell our peer that this is how long they'll have to wait if they perform
a unilateral close.
*max-locktime-blocks*='BLOCKS'::
The longest our funds can be delayed (ie. the longest *watchtime-blocks*
our peer can ask for, and also the longest HTLC timeout we will accept).
If our peer asks for longer, we'll refuse to create a channel, and if an
HTLC asks for longer, we'll refuse it.
*funding-confirms*='BLOCKS'::
Confirmations required for the funding transaction when the other side
opens a channel before the channel is usable.
*commit-fee*='PERCENT'::
The percentage of 'estimatesmartfee 2' to use for the bitcoin
transaction which funds a channel: can be greater than 100.
*commit-fee-min*='PERCENT'::
*commit-fee-max*='PERCENT'::
Limits on what onchain fee range we'll allow when a node opens a
channel with us, as a percentage of 'estimatesmartfee 2'. If
they're outside this range, we abort their opening attempt. Note
that *commit-fee-max* can (should!) be greater than 100.
*cltv-delta*='BLOCKS'::
The number of blocks between incoming payments and outgoing payments:
this needs to be enough to make sure that if we have to, we can close
the outgoing payment before the incoming, or redeem the incoming once
the outgoing is redeemed.
*cltv-final*='BLOCKS'::
The number of blocks to allow for payments we receive: if we have to,
we might need to redeem this on-chain, so this is the number of blocks
we have to do that.
Invoice control options:
*autocleaninvoice-cycle*='SECONDS'::
Perform cleanup of expired invoices every 'SECONDS' seconds, or
disable if 0. Usually unpaid expired invoices are uninteresting,
and just take up space in the database.
*autocleaninvoice-expired-by*='SECONDS'::
Control how long invoices must have been expired before they are
cleaned (if 'autocleaninvoice-cycle' is non-zero).
Networking options
~~~~~~~~~~~~~~~~~~
Note that for simple setups, the implicit 'autolisten' option does the
right thing: it will try to bind to port 9735 on IPv4 and IPv6, and
will announce it to peers if it seems like a public address.
You can instead use 'addr' to override this (eg. to change the port),
or precisely control where to bind and what to announce with the
'bind-addr' and 'announce-addr' options. These will *disable* the
'autolisten' logic, so you must specifiy exactly what you want!
*addr*='[IPADDRESS[:PORT]]|autotor:TORIPADDRESS[:TORPORT]'::
Set an IP address (v4 or v6) or automatic Tor address to listen on
and (maybe) announce as our node address.
An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or
IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4
interfaces, '::' means 'bind to all IPv6 interfaces'. If 'PORT' is
not specified, 9735 is used. If we can determine a public IP
address from the resulting binding, and no other addresses of the
same type are already announced, the address is announced.
If the argument begins with 'autotor:' then it is followed by the
IPv4 or IPv6 address of the Tor control port (default port 9051),
and this will be used to configure a Tor hidden service for port
9735. The Tor hidden service will be configured to point to the
first IPv4 or IPv6 address we bind to.
This option can be used multiple times to add more addresses, and
its use disables autolisten. If necessary, and 'always-use-proxy'
is not specified, a DNS lookup may be done to resolve 'IPADDRESS'
or 'TORIPADDRESS'.
*bind-addr*='[IPADDRESS[:PORT]]|SOCKETPATH'::
Set an IP address or UNIX domain socket to listen to, but do not
announce. A UNIX domain socket is distinguished from an IP address
by beginning with a '/'.
An empty 'IPADDRESS' is a special value meaning bind to IPv4 and/or
IPv6 on all interfaces, '0.0.0.0' means bind to all IPv4
interfaces, '::' means 'bind to all IPv6 interfaces'. 'PORT' is
not specified, 9735 is used.
This option can be used multiple times to add more addresses, and
its use disables autolisten. If necessary, and 'always-use-proxy'
is not specified, a DNS lookup may be done to resolve 'IPADDRESS'.
*announce-addr*='IPADDRESS[:PORT]|TORADDRESS.onion[:PORT]'::
Set an IP (v4 or v6) address or Tor address to announce; a Tor address is
distinguished by ending in '.onion'. 'PORT' defaults to 9735.
Empty or wildcard IPv4 and IPv6 addresses don't make sense here.
Also, unlike the 'addr' option, there is no checking that your
announced addresses are public (e.g. not localhost).
This option can be used multiple times to add more addresses, and
its use disables autolisten. The spec says you can't announce
more that one address of the same type (eg. two IPv4 or two IPv6
addresses) so `lightningd` will refuse if you specify more than one.
If necessary, and 'always-use-proxy' is not specified, a DNS
lookup may be done to resolve 'IPADDRESS'.
*offline*::
Do not bind to any ports, and do not try to reconnect to any peers.
This can be useful for maintenance and forensics, so is usually
specified on the command line. Overrides all 'addr' and 'bind-addr'
options.
*autolisten*='BOOL'::
By default, we bind (and maybe announce) on IPv4 and IPv6 interfaces if
no 'addr', 'bind-addr' or 'announce-addr' options are specified. Setting
this to 'false' disables that.
*proxy*='IPADDRESS[:PORT]'::
Set a socks proxy to use to connect to Tor nodes (or for all connections if
*always-use-proxy* is set).
*always-use-proxy*='BOOL'::
Always use the *proxy*, even to connect to normal IP addresses (you
can still connect to Unix domain sockets manually). This also disables
all DNS lookups, to avoid leaking information.
*disable-dns*::
Disable the DNS bootstrapping mechanism to find a node by its node ID.
*tor-service-password*='PASSWORD'::
Set a Tor control password, which may be needed for 'autotor:' to
authenticate to the Tor control port.
Lightning Plugins
~~~~~~~~~~~~~~~~~
lightningd(8) supports plugins, which offer additional configuration
options and JSON-RPC methods, depending on the plugin. Some are
supplied by default (usually located in
*libexec/c-lightning/plugins/*), but you can add your own, too.
*plugin*='PATH'::
Specify a plugin to run as part of c-lightning. This can be specified
multiple times to add multiple plugins.
*plugin-dir*='DIRECTORY'::
Specify a directory to look for plugins; all executable files
not containing punctuation (other than '.', '-' or '_) in 'DIRECTORY'
are loaded. 'DIRECTORY' must exist;
this can be specified multiple times to add multiple directories.
*clear-plugins*::
This option clears all 'plugin' and 'plugin-dir' options
preceeding it, including the default built-in plugin directory.
You can still add 'plugin-dir' and 'plugin' options following
this and they will have the normal effect.
*disable-plugin*='PLUGIN'::
If 'PLUGIN' contains a /, plugins with the same path as 'PLUGIN'
are disabled. Otherwise, any plugin with that base name is
disabled, whatever directory it is in.
BUGS
----
You should report bugs on our github issues page, and maybe submit a
fix to gain our eternal gratitude!
AUTHOR
------
Rusty Russell <[email protected]> wrote this man page, and much
of the configuration language, but many others did the hard work
of actually implementing these options.
SEE ALSO
--------
lightning-listconfigs(7) lightningd-setchannelfee(7)
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning
COPYING
-------
Note: the modules in the ccan/ directory have their own licenses, but
the rest of the code is covered by the BSD-style MIT license.