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,
       signet, or regtest).  This is not valid within the per-network configu-
       ration file.

	mainnet	Alias for network=bitcoin.

	testnet	Alias for network=testnet.

	signet Alias for network=signet.

	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 DB server running on localhost	port 5432, au-
       thenticate with username	user and password pass,	and then use the data-
       base  db_name.  The database must exist,	but the	schema will be managed
       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.   If	 there	is  no
       hsm_secret  yet,	lightningd will	create a new encrypted secret.	If you
       have an unencrypted hsm_secret you want to  encrypt  on-disk,  or  vice
       versa, see lightning-hsmtool(8).

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. This will reject any opening of a channel which can't pass an
       HTLC of least this value.  Usually this prevents	a peer opening a  tiny
       channel,	 but  it can also prevent a channel you	open with a reasonable
       amount and the peer requesting such a large reserve that	 the  capacity
       of the channel falls below this.

	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/CONSERVATIVE
       to use for the commitment transactions: default is 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

       Payment control options:

	disable-mpp Disable the	multi-part payment sending support in the  pay
       plugin.	By default the MPP support is enabled, but it can be desirable
       to disable in situations	in which each payment should result in a  sin-
       gle HTLC	being forwarded	in the network.

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).  The port
       defaults	to 9050	if not specified.

	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.  Note that	unless
       plugins themselves specify ordering requirements	for  being  called  on
       various	hooks,	plugins	 will  be  ordered by commandline, then	config

	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.	The ordering of	plugins	within
       a directory is currently	unspecified.

	clear-plugins This option clears  all  plugin,	important-plugin,  and
       plugin-dir options preceeding it, including the default built-in	plugin
       directory. You can still	add plugin-dir,	plugin,	 and  important-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 will not be loaded at startup. Otherwise,	no plugin with
       that  base name will be loaded at startup, whatever directory it	is in.
       This option is useful for disabling a single plugin inside a directory.
       You  can	 still explicitly load plugins which have been disabled, using
       lightning-plugin(7) start.

	important-plugin=PLUGIN	Speciy a plugin	to run as part of C-lightning.
       This  can be specified multiple times to	add multiple plugins.  Plugins
       specified via this option are considered	 so  important,	 that  if  the
       plugin  stops  for any reason (including	via lightning-plugin(7)	stop),
       C-lightning will	also stop running.  This way, you can monitor  crashes
       of  important  plugins  by simply monitoring if C-lightning terminates.
       Built-in	plugins, which are installed with lightningd(8), are automati-
       cally considered	important.

       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