You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
383 lines
14 KiB
383 lines
14 KiB
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 changed 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' and '--lightning-dir'
|
|
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(8) 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
|
|
lightning-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 lightning-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.
|
|
|
|
*max-concurrent-htlcs*='INTEGER'::
|
|
Number of HTLCs one channel can handle concurrently in each direction.
|
|
Should be between 1 and 483 (default 30).
|
|
|
|
*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/*). If a *plugins* directory exists
|
|
under 'lightning-dir' that is searched for plugins along with
|
|
any immediate subdirectories). You can specify additional paths 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 <rusty@rustcorp.com.au> 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) lightning-setchannelfee(7)
|
|
lightningd(8)
|
|
|
|
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.
|
|
|