Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
LIGHTNINGD-CONFIG(5)	       lightningd-config	  LIGHTNINGD-CONFIG(5)

       lightningd-config - Lightning daemon configuration file


       When  lightningd(8)  starts up it usually reads a general configuration
       file (default: $HOME/.lightning/config) then a network-specific config-
       uration	file  (default:	$HOME/.lightning/testnet/config).  This	can be
       changed:	see --conf and --lightning-dir.

       General configuration files are processed first,	then  network-specific
       ones,  then  command  line options: later options override earlier ones
       except addr options and log-level with subsystems, which	accumulate.

       include	followed by a filename includes	another	configuration file  at
       that point, relative to the current configuration file.

       All  these  options  are	 mirrored  as  commandline arguments to	light-
       ningd(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.

       --help will show	you the	defaults for many options; they	vary with net-
       work settings so	you can	specify	--network before --help	to see the de-
       faults for that network.

       The  lightning-listconfigs(7) command will output a valid configuration
       file using the current settings.

General	options
	allow-deprecated-apis=BOOL Enable  deprecated  options,	 JSONRPC  com-
       mands, fields, etc. It defaults to true,	but you	should set it to false
       when testing to ensure that an upgrade wonat break your configuration.

	help Print help	and exit. Not very useful inside a configuration file,
       but  fun	 to  put in otheras config files while their computer is unat-

	version	Print version and exit.	Also useless  inside  a	 configuration
       file,  but  putting  this in someoneas config file may convince them to
       read this man page.

       Bitcoin control options:

	network=NETWORK	Select the network parameters  (bitcoin,  testnet,  or
       regtest).  This is not valid within the per-network configuration file.

	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 bit-

	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  bit-
       coin-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 ab-
       solute  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.  This is
       only valid on the command-line, or in a configuration file specified by

	subdaemon=SUBDAEMON:PATH  Specifies  an	 alternate  subdaemon  binary.
       Current subdaemons are channeld,	closingd, connectd, gossipd, hsmd, on-
       chaind,	and  openingd.	If the supplied	path is	relative the subdaemon
       binary is found in the working directory. This option may be  specified
       multiple	times.

	So, subdaemon=hsmd:remote_signer would use a hypothetical remote sign-
       ing proxy instead of the	standard lightning_hsmd	binary.

	pid-file=PATH Specify pid file to write	to.

	log-level=LEVEL[:SUBSYSTEM] What log level to print out:  options  are
       io,  debug, info, unusual, broken.  If SUBSYSTEM	is supplied, this sets
       the logging level for any subsystem containing that string.  Subsystems

	      o	     lightningd: The main lightning daemon

	      o	     database: The database subsystem

	      o	     wallet: The wallet	subsystem

	      o	     gossipd: The gossip daemon

	      o	     plugin-manager: The plugin	subsystem

	      o	     plugin-P: Each plugin, P =	plugin path without directory

	      o	     hsmd: The secret-holding daemon

	      o	     connectd: The network connection daemon

	      o	     jsonrpc#FD: Each JSONRPC connection, FD = file descriptor

	 The following subsystems exist	for each channel, where	N is an	incre-
       menting internal	integer	id assigned for	the lifetime of	the channel:

	      o	     openingd-chan#N: Each opening / idling daemon

	      o	     channeld-chan#N: Each channel management daemon

	      o	     closingd-chan#N: Each closing negotiation daemon

	      o	     onchaind-chan#N: Each onchain close handling daemon

	 So, log-level=debug:plugin would set debug level logging on all plug-
       ins and the plugin manager.  log-level=io:chan#55 would set IO  logging
       on channel number 55 (or	550, for that matter).

	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	light-
       ningd(8)	SIGHUP will cause it to	reopen this file (useful for log rota-

	rpc-file=PATH Set JSON-RPC socket (or /dev/tty), such  as  for	light-

	rpc-file-mode=MODE  Set	 JSON-RPC socket file mode, as a 4-digit octal
       number.	Default	is 0600, meaning only the user	that  launched	light-
       ningd  can  command it.	Set to 0660 to allow users with	the same group
       to access the RPC as well.

	daemon Run in the background, suppress stdout and stderr.

	conf=PATH Sets configuration file, and disable reading the normal gen-
       eral  and  network  ones. 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	invalid.

	wallet=DSN Identify the	location of the	wallet.	This is	a fully	quali-
       fied  data  source name,	including a scheme such	as sqlite3 or postgres
       followed	by the connection parameters.

       The default wallet corresponds to the following DSN:


       The following is	an example of a	postgresql wallet DSN:


       This will connect to a the DB server running on	localhost  port	 5432,
       authenticate  with  username  user  and password	pass, and then use the
       database	db_name. The database must exist, but the schema will be  man-
       aged automatically by lightningd.

	encrypted-hsm If set, you will be prompted to enter a password used to
       encrypt the hsm_secret.	Note that once you encrypt the hsm_secret this
       option will be mandatory	for lightningd to start.

Lightning node customization options
	alias=NAME  Up	to 32 bytes of UTF-8 characters	to tag your node. Com-
       pletely silly, since anyone can call their node anything	they want. The
       default is an NSA-style codename	derived	from your public key, but "Pe-
       ter Todd" and "VAULTERO"	are good options, too.

	rgb=RRGGBB Your	favorite color as a hex	code.

	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  propor-
       tional  fee  to	charge for every payment which passes through. As per-
       centages	are too	coarse,	itas in	millionths, so 10000 is	 1%,  1000  is
       0.1%.  Changing this value will only affect new channels	and not	exist-
       ing 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 mini-
       mal 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
	large-channels	Removes	capacity limits	for channel creation.  Version
       1.0 of the specification	limited	channel	 sizes	to  16777215  satoshi.
       With  this  option (which your node will	advertize to peers), your node
       will accept larger incoming channels and	if the peer supports it,  will
       open  larger channels.  Note: this option is spelled large-channels but
       it's pronounced wumbo.

	watchtime-blocks=BLOCKS	How long we need to spot an outdated close at-
       tempt:  on  opening  a  channel	we tell	our peer that this is how long
       theyall 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, weall	refuse
       to create a channel, and	if an HTLC asks	for longer, weall refuse it.

	funding-confirms=BLOCKS	 Confirmations required	for the	funding	trans-
       action when the other side opens	a channel before the  channel  is  us-

	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-max=PERCENT Limits on what onchain fee  range  weall	 allow
       when  a node opens a channel with us, as	a percentage of	estimatesmart-
       fee 2. If theyare 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

	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  re-
       ceive: 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 ev-
       ery  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

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!


       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, '' 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 result-
       ing binding, 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.

       If the argument begins with 'statictor:'	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	static 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 and is by default unique	to your	 nodes
       id.  You	can add	the text '/torblob=BLOB' followed by up	to 64 Bytes of
       text to generate	from this text a v3 onion service address text	unique
       to  the first 32	Byte of	this text.  You	can also use an	postfix	'/tor-
       port=TORPORT' to	select the external tor	binding. The  result  is  that
       over  tor your node is accessible by a port defined by you and possible
       different from your local node port assignment

       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 'TORIPAD-

	bind-addr=[IPADDRESS[:PORT]]|SOCKETPATH	 Set an	IP address or UNIX do-
       main 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, '' 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 distin-
       guished 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 ad-
       dresses are public (e.g.	not localhost).

       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'.

	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  op-

	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.

	enable-autotor-v2-mode Try to get a v2 onion address from the Tor ser-
       vice call, default is v3.

	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  sup-
       plied  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 addi-
       tional 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 exe-
       cutable files not containing punctuation	(other than ., - or _) in 'DI-
       RECTORY	are loaded. DIRECTORY must exist; this can be specified	multi-
       ple 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.

       You  should  report  bugs on our	github issues page, and	maybe submit a
       fix to gain our eternal gratitude!

       Rusty Russell <> wrote this  man  page,  and
       much  of	 the configuration language, but many others did the hard work
       of actually implementing	these options.

       lightning-listconfigs(7)	lightning-setchannelfee(7) lightningd(8)

       Main web	site:

       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.


NAME | SYNOPSIS | DESCRIPTION | DEBUGGING | OPTIONS | General options | Lightning daemon options | Lightning node customization options | Lightning channel and HTLC options | Networking options | Lightning Plugins | BUGS | AUTHOR | SEE ALSO | RESOURCES | COPYING

Want to link to this manual page? Use this URL:

home | help