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.
495 lines
16 KiB
495 lines
16 KiB
.TH "LIGHTNINGD-CONFIG" "5" "" "" "lightningd-config"
|
|
.SH NAME
|
|
lightningd-config - Lightning daemon configuration file
|
|
.SH SYNOPSIS
|
|
|
|
\fB~/\.lightning/config\fR
|
|
|
|
.SH DESCRIPTION
|
|
|
|
When \fBlightningd\fR(8) starts up, it reads a configuration file\. By default
|
|
that is \fIconfig\fR in the \fB\.lightning\fR subdirectory of the home
|
|
directory (if it exists), but that can be changed by the
|
|
\fI--lightning-dir\fR or \fI--conf\fR options on the \fBlightningd\fR(8) command line\.
|
|
|
|
|
|
Configuration file options are processed first, then command line
|
|
options: later options override earlier ones except \fIaddr\fR options
|
|
and \fIlog-level\fR with subsystems, which accumulate\.
|
|
|
|
|
|
All these options are mirrored as commandline arguments to
|
|
\fBlightningd\fR(8), so \fI--foo\fR becomes simply \fIfoo\fR in the configuration
|
|
file, and \fI--foo=bar\fR becomes \fIfoo=bar\fR in the configuration file\.
|
|
|
|
|
|
Blank lines and lines beginning with \fI#\fR are ignored\.
|
|
|
|
.SH DEBUGGING
|
|
|
|
\fI--help\fR will show you the defaults for many options; they vary with
|
|
network settings so you can specify \fI--network\fR before \fI--help\fR to see
|
|
the defaults for that network\.
|
|
|
|
|
|
The \fBlightning-listconfigs\fR(7) command will output a valid configuration
|
|
file using the current settings\.
|
|
|
|
.SH OPTIONS
|
|
.SH General options
|
|
|
|
\fBallow-deprecated-apis\fR=\fIBOOL\fR
|
|
Enable deprecated options, JSONRPC commands, fields, etc\. It defaults to
|
|
\fItrue\fR, but you should set it to \fIfalse\fR when testing to ensure that an
|
|
upgrade won’t break your configuration\.
|
|
|
|
|
|
\fBhelp\fR
|
|
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\.
|
|
|
|
|
|
\fBversion\fR
|
|
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:
|
|
|
|
|
|
\fBnetwork\fR=\fINETWORK\fR
|
|
Select the network parameters (\fIbitcoin\fR, \fItestnet\fR, or \fIregtest\fR)\.
|
|
|
|
|
|
\fBtestnet\fR
|
|
Alias for \fInetwork=testnet\fR\.
|
|
|
|
|
|
\fBsignet\fR
|
|
Alias for \fInetwork=signet\fR\.
|
|
|
|
|
|
\fBmainnet\fR
|
|
Alias for \fInetwork=bitcoin\fR\.
|
|
|
|
|
|
\fBbitcoin-cli\fR=\fIPATH\fR
|
|
The name of \fIbitcoin-cli\fR executable to run\.
|
|
|
|
|
|
\fBbitcoin-datadir\fR=\fIDIR\fR
|
|
\fI-datadir\fR argument to supply to \fBbitcoin-cli\fR(1)\.
|
|
|
|
|
|
\fBbitcoin-rpcuser\fR=\fIUSER\fR
|
|
The RPC username for talking to \fBbitcoind\fR(1)\.
|
|
|
|
|
|
\fBbitcoin-rpcpassword\fR=\fIPASSWORD\fR
|
|
The RPC password for talking to \fBbitcoind\fR(1)\.
|
|
|
|
|
|
\fBbitcoin-rpcconnect\fR=\fIHOST\fR
|
|
The \fBbitcoind\fR(1) RPC host to connect to\.
|
|
|
|
|
|
\fBbitcoin-rpcport\fR=\fIPORT\fR
|
|
The \fBbitcoind\fR(1) RPC port to connect to\.
|
|
|
|
|
|
\fBbitcoin-retry-timeout\fR=\fISECONDS\fR
|
|
Number of seconds to keep trying a \fBbitcoin-cli\fR(1) command\. If the
|
|
command keeps failing after this time, exit with a fatal error\.
|
|
|
|
|
|
\fBrescan\fR=\fIBLOCKS\fR
|
|
Number of blocks to rescan from the current head, or absolute
|
|
blockheight if negative\. This is only needed if something goes badly
|
|
wrong\.
|
|
|
|
.SH Lightning daemon options
|
|
|
|
\fBlightning-dir\fR=\fIDIR\fR
|
|
Sets the working directory\. All files (except \fI--conf\fR and
|
|
\fI--lightning-dir\fR on the command line) are relative to this\.
|
|
|
|
|
|
\fBpid-file\fR=\fIPATH\fR
|
|
Specify pid file to write to\.
|
|
|
|
|
|
\fBlog-level\fR=\fILEVEL\fR[:\fISUBSYSTEM\fR]
|
|
What log level to print out: options are io, debug, info, unusual,
|
|
broken\. If \fISUBSYSTEM\fR is supplied, this sets the logging level
|
|
for any subsystem containing that string\. Subsystems include:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fIlightningd\fR: The main lightning daemon
|
|
.IP \[bu]
|
|
\fIdatabase\fR: The database subsystem
|
|
.IP \[bu]
|
|
\fIwallet\fR: The wallet subsystem
|
|
.IP \[bu]
|
|
\fIgossipd\fR: The gossip daemon
|
|
.IP \[bu]
|
|
\fIplugin-manager\fR: The plugin subsystem
|
|
.IP \[bu]
|
|
\fIplugin-P\fR: Each plugin, P = plugin path without directory
|
|
.IP \[bu]
|
|
\fIhsmd\fR: The secret-holding daemon
|
|
.IP \[bu]
|
|
\fIgossipd\fR: The gossip daemon
|
|
.IP \[bu]
|
|
\fIconnectd\fR: The network connection daemon
|
|
|
|
.RE
|
|
|
|
The following subsystems exist for each channel, where N is an incrementing
|
|
internal integer id assigned for the lifetime of the channel:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fIopeningd-chan #N\fR: Each opening / idling daemon
|
|
.IP \[bu]
|
|
\fIchanneld-chan #N\fR: Each channel management daemon
|
|
.IP \[bu]
|
|
\fIclosingd-chan #N\fR: Each closing negotiation daemon
|
|
.IP \[bu]
|
|
\fIonchaind-chan #N\fR: Each onchain close handling daemon
|
|
.IP \[bu]
|
|
|
|
\fIjson #FD\fR: Each JSONRPC connection, FD = file descriptor number
|
|
|
|
|
|
\fBlog-prefix\fR=\fIPREFIX\fR
|
|
Prefix for log lines: this can be customized if you want to merge logs
|
|
with multiple daemons\.
|
|
|
|
|
|
\fBlog-file\fR=\fIPATH\fR
|
|
Log to this file instead of stdout\. Sending \fBlightningd\fR(8) SIGHUP will
|
|
cause it to reopen this file (useful for log rotation)\.
|
|
|
|
|
|
\fBrpc-file\fR=\fIPATH\fR
|
|
Set JSON-RPC socket (or /dev/tty), such as for \fBlightning-cli\fR(1)\.
|
|
|
|
|
|
\fBdaemon\fR
|
|
Run in the background, suppress stdout and stderr\.
|
|
|
|
|
|
\fBconf\fR=\fIPATH\fR
|
|
Sets configuration file (default: \fBlightning-dir\fR/\fIconfig\fR )\. If this
|
|
is a relative path, it is relative to the starting directory, not
|
|
\fBlightning-dir\fR (unlike other paths)\. \fIPATH\fR must exist and be
|
|
readable (we allow missing files in the default case)\. Using this inside
|
|
a configuration file is meaningless\.
|
|
|
|
|
|
\fBwallet\fR=\fIDSN\fR
|
|
Identify the location of the wallet\. This is a fully qualified data source
|
|
name, including a scheme such as \fBsqlite3\fR or \fBpostgres\fR followed by the
|
|
connection parameters\.
|
|
|
|
|
|
\fBencrypted-hsm\fR
|
|
If set, you will be prompted to enter a password used to encrypt the \fBhsm_secret\fR\.
|
|
Note that once you encrypt the \fBhsm_secret\fR this option will be mandatory for
|
|
\fBlightningd\fR to start\.
|
|
|
|
|
|
|
|
.RE
|
|
.SH Lightning node customization options
|
|
|
|
\fBalias\fR=\fIRRGGBB\fR
|
|
\fBrgb\fR=\fIRRGGBB\fR
|
|
Your favorite color as a hex code\.
|
|
|
|
|
|
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\.
|
|
|
|
|
|
\fBfee-base\fR=\fIMILLISATOSHI\fR
|
|
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
|
|
\fBlightning-setchannelfee\fR(7)\.
|
|
|
|
|
|
\fBfee-per-satoshi\fR=\fIMILLIONTHS\fR
|
|
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 \fBlightning-setchannelfee\fR(7)\.
|
|
|
|
|
|
\fBmin-capacity-sat\fR=\fISATOSHI\fR
|
|
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\.
|
|
|
|
|
|
\fBignore-fee-limits\fR=\fIBOOL\fR
|
|
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\.
|
|
|
|
|
|
\fBcommit-time\fR='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\.
|
|
|
|
.SH Lightning channel and HTLC options
|
|
|
|
\fBwatchtime-blocks\fR=\fIBLOCKS\fR
|
|
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\.
|
|
|
|
|
|
\fBmax-locktime-blocks\fR=\fIBLOCKS\fR
|
|
The longest our funds can be delayed (ie\. the longest
|
|
\fBwatchtime-blocks\fR 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\.
|
|
|
|
|
|
\fBfunding-confirms\fR=\fIBLOCKS\fR
|
|
Confirmations required for the funding transaction when the other side
|
|
opens a channel before the channel is usable\.
|
|
|
|
|
|
\fBcommit-fee\fR=\fIPERCENT\fR
|
|
The percentage of \fIestimatesmartfee 2\fR to use for the bitcoin
|
|
transaction which funds a channel: can be greater than 100\.
|
|
|
|
|
|
\fBcommit-fee-min\fR=\fIPERCENT\fR
|
|
\fBcommit-fee-max\fR=\fIPERCENT\fR
|
|
Limits on what onchain fee range we’ll allow when a node opens a channel
|
|
with us, as a percentage of \fIestimatesmartfee 2\fR\. If they’re outside
|
|
this range, we abort their opening attempt\. Note that \fBcommit-fee-max\fR
|
|
can (should!) be greater than 100\.
|
|
|
|
|
|
\fBmax-concurrent-htlcs\fR=\fIINTEGER\fR
|
|
Number of HTLCs one channel can handle concurrently in each direction\.
|
|
Should be between 1 and 483 (default 30)\.
|
|
|
|
|
|
\fBcltv-delta\fR=\fIBLOCKS\fR
|
|
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\.
|
|
|
|
|
|
\fBcltv-final\fR=\fIBLOCKS\fR
|
|
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:
|
|
|
|
|
|
\fBautocleaninvoice-cycle\fR=\fISECONDS\fR
|
|
Perform cleanup of expired invoices every \fISECONDS\fR seconds, or disable
|
|
if 0\. Usually unpaid expired invoices are uninteresting, and just take
|
|
up space in the database\.
|
|
|
|
|
|
\fBautocleaninvoice-expired-by\fR=\fISECONDS\fR
|
|
Control how long invoices must have been expired before they are cleaned
|
|
(if \fIautocleaninvoice-cycle\fR is non-zero)\.
|
|
|
|
.SH Networking options
|
|
|
|
Note that for simple setups, the implicit \fIautolisten\fR 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 \fIaddr\fR to override this (eg\. to change the port), or
|
|
precisely control where to bind and what to announce with the
|
|
\fIbind-addr\fR and \fIannounce-addr\fR options\. These will \fBdisable\fR the
|
|
\fIautolisten\fR logic, so you must specifiy exactly what you want!
|
|
|
|
|
|
\fBaddr\fR=\fI[IPADDRESS[:PORT]]|autotor:TORIPADDRESS[:TORPORT]\fR
|
|
Set an IP address (v4 or v6) or automatic Tor address to listen on and
|
|
(maybe) announce as our node address\.
|
|
|
|
.nf
|
|
.RS
|
|
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'.
|
|
|
|
|
|
.RE
|
|
|
|
.fi
|
|
|
|
\fBbind-addr\fR=\fI[IPADDRESS[:PORT]]|SOCKETPATH\fR
|
|
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 \fI/\fR\.
|
|
|
|
.nf
|
|
.RS
|
|
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'.
|
|
|
|
|
|
.RE
|
|
|
|
.fi
|
|
|
|
\fBannounce-addr\fR=\fIIPADDRESS[:PORT]|TORADDRESS\.onion[:PORT]\fR
|
|
Set an IP (v4 or v6) address or Tor address to announce; a Tor address
|
|
is distinguished by ending in \fI\.onion\fR\. \fIPORT\fR defaults to 9735\.
|
|
|
|
.nf
|
|
.RS
|
|
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'.
|
|
|
|
|
|
.RE
|
|
|
|
.fi
|
|
|
|
\fBoffline\fR
|
|
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 \fIaddr\fR and \fIbind-addr\fR options\.
|
|
|
|
|
|
\fBautolisten\fR=\fIBOOL\fR
|
|
By default, we bind (and maybe announce) on IPv4 and IPv6 interfaces if
|
|
no \fIaddr\fR, \fIbind-addr\fR or \fIannounce-addr\fR options are specified\. Setting
|
|
this to \fIfalse\fR disables that\.
|
|
|
|
|
|
\fBproxy\fR=\fIIPADDRESS[:PORT]\fR
|
|
Set a socks proxy to use to connect to Tor nodes (or for all connections
|
|
if \fBalways-use-proxy\fR is set)\.
|
|
|
|
|
|
\fBalways-use-proxy\fR=\fIBOOL\fR
|
|
Always use the \fBproxy\fR, 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\.
|
|
|
|
|
|
\fBdisable-dns\fR
|
|
Disable the DNS bootstrapping mechanism to find a node by its node ID\.
|
|
|
|
|
|
\fBenable-autotor-v2-mode\fR
|
|
Try to get a v2 onion address from the Tor service call, default is v3\.
|
|
|
|
|
|
\fBtor-service-password\fR=\fIPASSWORD\fR
|
|
Set a Tor control password, which may be needed for \fIautotor:\fR to
|
|
authenticate to the Tor control port\.
|
|
|
|
.SH Lightning Plugins
|
|
|
|
\fBlightningd\fR(8) supports plugins, which offer additional configuration
|
|
options and JSON-RPC methods, depending on the plugin\. Some are supplied
|
|
by default (usually located in \fBlibexec/c-lightning/plugins/\fR)\. If a
|
|
\fBplugins\fR directory exists under \fIlightning-dir\fR that is searched for
|
|
plugins along with any immediate subdirectories)\. You can specify
|
|
additional paths too:
|
|
|
|
|
|
\fBplugin\fR=\fIPATH\fR
|
|
Specify a plugin to run as part of c-lightning\. This can be specified
|
|
multiple times to add multiple plugins\.
|
|
|
|
|
|
\fBplugin-dir\fR=\fIDIRECTORY\fR
|
|
Specify a directory to look for plugins; all executable files not
|
|
containing punctuation (other than \fI\.\fR, \fI-\fR or \fI_) in 'DIRECTORY\fR are
|
|
loaded\. \fIDIRECTORY\fR must exist; this can be specified multiple times to
|
|
add multiple directories\.
|
|
|
|
|
|
\fBclear-plugins\fR
|
|
This option clears all \fIplugin\fR and \fIplugin-dir\fR options preceeding it,
|
|
including the default built-in plugin directory\. You can still add
|
|
\fIplugin-dir\fR and \fIplugin\fR options following this and they will have the
|
|
normal effect\.
|
|
|
|
|
|
\fBdisable-plugin\fR=\fIPLUGIN\fR
|
|
If \fIPLUGIN\fR contains a /, plugins with the same path as \fIPLUGIN\fR are
|
|
disabled\. Otherwise, any plugin with that base name is disabled,
|
|
whatever directory it is in\.
|
|
|
|
.SH BUGS
|
|
|
|
You should report bugs on our github issues page, and maybe submit a fix
|
|
to gain our eternal gratitude!
|
|
|
|
.SH AUTHOR
|
|
|
|
Rusty Russell <\fIrusty@rustcorp.com.au\fR> wrote this man page, and
|
|
much of the configuration language, but many others did the hard work of
|
|
actually implementing these options\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-listconfigs\fR(7) \fBlightning-setchannelfee\fR(7) \fBlightningd\fR(8)
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
.SH 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\.
|
|
|
|
|