lightningd-config -- Lightning daemon configuration file
========================================================

SYNOPSIS
--------

**~/.lightning/config**

DESCRIPTION
-----------

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

Note that some configuration options, marked *dynamic* can be changed at runtime: see lightning-setconfig(7): by default this will write to a file called **config.setconfig** in the network-specific lightning directory, unless there is another config file with a name ending in ".setconfig".

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

* **developer**

  This enables developer mode, allowing developer options and commands to be used.  It also disabled deprecated APIs; use `allow-deprecated-apis=true` to re-enable them.

* **allow-deprecated-apis**=*BOOL*

  Enable deprecated options, JSONRPC commands, fields, etc. It defaults to
*true* outside developer mode, 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.

* **database-upgrade**=*BOOL*

  Upgrades to Core Lightning often change the database: once this is done,
downgrades are not generally possible.  By default, Core Lightning will
exit with an error rather than upgrade, unless this is an official released
version.  If you really want to upgrade to a non-release version, you can
set this to *true* (or *false* to never allow a non-reversible upgrade!).

* **i-promise-to-fix-broken-api-user**=*FEATURE*

  Deprecated features get removed slowly (over 3 releases), but
sometimes people still get surprised when they are finally removed.
As long as they haven't been actually fully removed, this option will
re-enable it.  Unless we've made a horrible mistake it's probably time
to complain or fix to whatever is using the old API.  It can be
specified multiple times for different features.

### Whitespace Handling

Because it's a common error, we automatically trim whitespace from the
end of most configuration options. Exceptions are noted below:

- `log-prefix`: Preserves whitespace at the end.
- `alias`: Preserves whitespace at the end.

### Bitcoin control options:

Bitcoin control options:

* **network**=*NETWORK*

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

* **mainnet**

  Alias for *network=bitcoin*.

* **regtest**

  Alias for *network=regtest* (added in v23.08)

* **testnet**

  Alias for *network=testnet*.

* **testnet4**

  Alias for *network=testnet4*.

* **signet**

  Alias for *network=signet*.

* **bitcoin-cli**=*PATH* [plugin `bcli`]

  The name of *bitcoin-cli* executable to run.

* **bitcoin-datadir**=*DIR* [plugin `bcli`]

  *-datadir* argument to supply to bitcoin-cli(1).

* **bitcoin-rpcuser**=*USER* [plugin `bcli`]

  The RPC username for talking to bitcoind(1).

* **bitcoin-rpcpassword**=*PASSWORD* [plugin `bcli`]

  The RPC password for talking to bitcoind(1).

* **bitcoin-rpcconnect**=*HOST* [plugin `bcli`]

  The bitcoind(1) RPC host to connect to.

* **bitcoin-rpcport**=*PORT* [plugin `bcli`]

  The bitcoind(1) RPC port to connect to.

* **bitcoin-rpcclienttimeout**=*SECONDS* [plugin `bcli`]

  The bitcoind(1) RPC client timeout in seconds. Default is set to 60
instead of 900 to match bitcoin-retry-timeout default. When set
explicitly, the higher value of it and bitcoin-retry-timeout is used.

* **bitcoin-retry-timeout**=*SECONDS* [plugin `bcli`]

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

* **subdaemon**=*SUBDAEMON*:*PATH*

  Specifies an alternate subdaemon binary.
Current subdaemons are *channeld*, *closingd*,
*connectd*, *gossipd*, *hsmd*, *onchaind*, 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 signing proxy instead of the standard *lightning\_hsmd*
binary.

* **pid-file**=*PATH*

  Specify pid file to write to.

* **log-level**=*LEVEL*\[:*SUBSYSTEM*\]\[:*PATH*\]

  What log level to print out: options are io, trace, debug, info, unusual,
broken.  If *SUBSYSTEM* is supplied, this sets the logging level
for any subsystem (or *nodeid*) containing that string. If *PATH* is supplied, it means this log-level filter is only applied to that `log-file`, which is useful for creating logs to capture a specific subsystem.  This option may be specified multiple times.
Subsystems include:

  * *lightningd*: The main lightning daemon

  * *database*: The database subsystem

  * *wallet*: The wallet subsystem

  * *gossipd*: The gossip daemon

  * *plugin-manager*: The plugin subsystem

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

  * *hsmd*: The secret-holding daemon

  * *connectd*: The network connection daemon

  * *jsonrpc#FD*: Each JSONRPC connection, FD = file descriptor number


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

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

  * *channeld-chan#N*: Each channel management daemon

  * *closingd-chan#N*: Each closing negotiation daemon

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


  So, **log-level=debug:plugin** would set debug level logging on all
plugins and the plugin manager.  **log-level=io:chan#55** would set
IO logging on channel number 55 (or 550, for that matter).
**log-level=debug:024b9a1fa8:/tmp/024b9a1fa8.debug.log** would set debug logging for that channel only on the **log-file=/tmp/024b9a1fa8.debug.log** (or any node id containing that string).

* **log-prefix**=*PREFIX*

  Prefix for all log lines: this can be customized if you want to merge logs
with multiple daemons.  Usually you want to include a space at the end of *PREFIX*,
as the timestamp follows immediately.

* **log-file**=*PATH*

  Log to this file (instead of stdout).  If you specify this more than once
you'll get more than one log file: **-** is used to mean stdout.  Sending
lightningd(8) SIGHUP will cause it to reopen each file (useful for log
rotation).

* **log-timestamps**=*BOOL*

  Set this to false to turn off timestamp prefixes (they will still appear
in crash log files).

* **rpc-file**=*PATH*

  Set JSON-RPC socket (or /dev/tty), such as for lightning-cli(1).

* **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 lightningd
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.  Note that you need
to specify **log-file** for this case.

* **conf**=*PATH*

  Sets configuration file, and disable reading the normal general 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 qualified data source
name, including a scheme such as `sqlite3` or `postgres` followed by the
connection parameters.

  The default wallet corresponds to the following DSN:
  `--wallet=sqlite3://$HOME/.lightning/bitcoin/lightningd.sqlite31`

  For the `sqlite3` scheme, you can specify a single backup database file
by separating it with a `:` character, like so:
  `--wallet=sqlite3://$HOME/.lightning/bitcoin/lightningd.sqlite3:/backup/lightningd.sqlite3`

  The following is an example of a postgresql wallet DSN:

  `--wallet=postgres://user:pass@localhost:5432/db_name`

  This will connect to a 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 managed
automatically by `lightningd`.

* **hsm-passphrase**

  If set, you will be prompted to enter a passphrase for your HSM secret.
  This option supports both legacy 32-byte `hsm_secret` files (where the passphrase
  encrypts the secret) and new BIP39 mnemonic-based secrets (where the passphrase
  is used as additional entropy during seed derivation according to the BIP39 standard).
  
  Note that once you set a passphrase, this option will be mandatory for
  `lightningd` to start. If there is no HSM secret yet, `lightningd` will create 
  a new mnemonic-based secret that will be secured with your passphrase following
  BIP39 specifications.
  
  For legacy users: If you have an existing encrypted `hsm_secret` that was created
  with the deprecated `encrypted-hsm` option, this will continue to work seamlessly.
  
  For new mnemonic-based secrets: The passphrase becomes part of the seed derivation
  process as specified in BIP39, providing an additional factor of security. The 
  mnemonic words alone are not sufficient to derive the seed without the passphrase.
  
  If you have an unencrypted legacy `hsm_secret` you want to encrypt, or need to
  manage your HSM secrets, see lightning-hsmtool(8).

  (Note: This option replaces the deprecated `encrypted-hsm` option.)


* **grpc-host**=*HOST* [plugin `cln-grpc`]

  Defines the GRPC server host. Default is 127.0.0.1.

* **grpc-port**=*portnum* [plugin `cln-grpc`]

  The port number for the GRPC plugin to listen for incoming
connections. Default is 9736.

* **grpc-msg-buffer-size**=*number* [plugin `cln-grpc`]

  The size of the buffer used by the GRPC-plugin. This buffer stores
  notifications between receiving them from lightningd and forwarding
  them over grpc. If buffer overflow occurs some notifications will not
  be delivered.

### Lightning node customization options

* **recover**=*mnemonic*

  Restore the node from a mnemonic.  For pre-25.12 nodes (which didn't have a mnemonic), use a 32-byte secret encoded as either a codex32 secret string or a 64-character hex string.
  
  This will fail if the `hsm_secret` file exists.  Your node will start the node in offline mode, for manual recovery.  The secret can be extracted from the `hsm_secret` using lightning-hsmtool(8)'s `getsecret`.

* **alias**=*NAME*

  Up to 32 bytes of 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.

* **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-setchannel(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-setchannel(7).

* **min-capacity-sat**=*SATOSHI* [*dynamic*]

  Default: 10000. This value defines the minimal 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.  Note that this can be set on a per-channel
basis with lightning-setchannel(7).

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

* **force-feerates**==*VALUES*

  Networks like regtest and testnet have unreliable fee estimates: we
usually treat them as the minimum (253 sats/kw) if we can't get them.
This allows override of one or more of our standard feerates (see
lightning-feerates(7)).  Up to 5 values, separated by '/' can be
provided: if fewer are provided, then the final value is used for the
remainder.  The values are in per-kw (roughly 1/4 of bitcoind's per-kb
values), and the order is "opening", "mutual\_close", "unilateral\_close",
"delayed\_to\_us", "htlc\_resolution", and "penalty".

  You would usually put this option in the per-chain config file, to avoid
setting it on Bitcoin mainnet!  e.g. `~rusty/.lightning/regtest/config`.

* **htlc-minimum-msat**=*MILLISATOSHI*

  Default: 0. Sets the minimal allowed HTLC value for newly created channels.
If you want to change the `htlc_minimum_msat` for existing channels, use the
RPC call lightning-setchannel(7).

* **htlc-maximum-msat**=*MILLISATOSHI*

  Default: unset (no limit). Sets the maximum allowed HTLC value for newly created
channels. If you want to change the `htlc_maximum_msat` for existing channels,
use the RPC call lightning-setchannel(7).

* **announce-addr-discovered**=*BOOL*

  Explicitly control the usage of discovered public IPs in `node_announcement` updates.
  Default: 'auto' - Only if we don't have anything else to announce.
  Note: You also need to open TCP port 9735 on your router towards your node.
  Note: Will always be disabled if you use 'always-use-proxy'.

* **announce-addr-discovered-port**=*PORT*
  Sets the public TCP port to use for announcing dynamically discovered IPs.
  If unset, this defaults to the selected networks lightning port,
  which is 9735 on mainnet.

### Lightning channel and HTLC options

* **large-channels** (deprecated in v23.11)

  As of v23.11, this is the default (and thus, the option is ignored).  Previously if you didn't specify this, channel sizes were limited to 16777215 satoshi.  Note: this option is spelled **large-channels** but it's pronounced **wumbo**.

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

* (deprecated in v23.05) **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/CONSERVATIVE* to use for the commitment
transactions: default is 100.

* **commit-feerate-offset**=*INTEGER*

  The additional feerate a channel opener adds to their preferred feerate to
lessen the odds of a disconnect due to feerate disagreement (default 5).

* **max-concurrent-htlcs**=*INTEGER*

  Number of HTLCs one channel can handle concurrently in each direction.
Should be between 1 and 483 (default 30).

* **max-dust-htlc-exposure-msat**=*MILLISATOSHI*

  Option which limits the total amount of sats to be allowed as dust on a channel.

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

* **accept-htlc-tlv-type**=*types*

  Normally HTLC onions which contain unknown even fields are rejected.
This option specifies that this type is to be accepted, and ignored.  Can be
specified multuple times. (Added in v23.08).

* **min-emergency-msat**=*msat*

  This is the amount of funds to keep in the wallet to close anchor channels (which don't carry their own transaction fees).  It defaults to 25000sat, and is only maintained if there are any anchor channels (or, when opening an anchor channel).  This amount may be insufficient for multiple closes at once, however.

### Cleanup control options:

* **autoclean-cycle**=*SECONDS* [plugin `autoclean`, *dynamic*]

  Perform search for things to clean every *SECONDS* seconds (default
3600, or 1 hour, which is usually sufficient).

* **autoclean-networkevents-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

How old network events (in `listnetworkevents`) have to be before deletion (default 30 days, i.e. 2592000 seconds)

* **autoclean-succeededforwards-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

  How old successful forwards (`settled` in listforwards `status`) have to be before deletion (default 0, meaning never).

* **autoclean-failedforwards-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

  How old failed forwards (`failed` or `local_failed` in listforwards `status`) have to be before deletion (default 0, meaning never).

* **autoclean-succeededpays-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

  How old successful payments (`complete` in listpays `status`) have to be before deletion (default 0, meaning never).

* **autoclean-failedpays-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

  How old failed payment attempts (`failed` in listpays `status`) have to be before deletion (default 0, meaning never).

* **autoclean-paidinvoices-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

  How old invoices which were paid (`paid` in listinvoices `status`) have to be before deletion (default 0, meaning never).

* **autoclean-expiredinvoices-age**=*SECONDS* [plugin `autoclean`, *dynamic*]

  How old invoices which were not paid (and cannot be) (`expired` in listinvoices `status`) before deletion (default 0, meaning never).

Note: prior to v22.11, forwards for channels which were closed were
not easily distinguishable.  As a result, autoclean may delete more
than one of these at once, and then suffer failures when it fails to
delete the others.

### Payment and invoice control options:

* **disable-mpp** [plugin `pay`]

  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 single HTLC being forwarded in the
network.

* **invoices-onchain-fallback**

  Add a (taproot) fallback address to invoices produced by the `invoice`
command, so they invoices can also be paid onchain.

* **xpay-handle-pay**=*BOOL* [plugin `xpay`, *dynamic*]

  Setting this makes `xpay` intercept simply `pay` commands (default `false`).

* **xpay-slow-mode**=*BOOL* [plugin `xpay`, *dynamic*]

  Setting this makes `xpay` wait until all parts have failed/succeeded before returning.  Usually this is unnecessary, as xpay will return on the first success (we have the preimage, if they don't take all the parts that's their problem) or failure (the destination could succeed another part, but it would mean it was only partially paid).  The default is `false`.

* **askrene-timeout**=*SECONDS* [plugin `askrene`, *dynamic*]

  This option makes the `getroutes` call fail if it takes more than this many seconds.  Setting it to zero is a fun way to ensure your node never makes payments.

* **askrene-max-threads**=*NUMBER* [plugin `askrene`, *dynamic*]

  This option controls how many routes askrene will calculate at once: this is only useful on nodes which make multiple payments at once, and setting the number higher than your number of cores/CPUS will not help.  The default is 4.

### Networking options

Note that for simple setups, the implicit *autolisten* option does the
right thing: for the mainnet (bitcoin) network 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 (and other default ports for other networks,
as described below).

Core Lightning also support IPv4/6 address discovery behind NAT routers.
If your node detects an new public address, it will update its announcement.
For this to work you need to forward the default TCP port 9735 to your node.
IP discovery is only active if no other addresses are announced.

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 specify exactly what you want!

* **addr**=*\[IPADDRESS\[:PORT\]\]|autotor:TORIPADDRESS\[:SERVICEPORT\]\[/torport=TORPORT\]|statictor:TORIPADDRESS\[:SERVICEPORT\]\[/torport=TORPORT\]\[/torblob=\[blob\]\]|HOSTNAME\[:PORT\]*

  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 you want to
specify an IPv6 address *and* a port, use `[]` around the IPv6
address, like `[::]:9750`).
  If 'PORT' is not specified, the default port 9735 is used for mainnet
(testnet: 19735, signet: 39735, regtest: 19846, testnet4: 49735).
If we can determine a public IP address from the resulting 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
in case of mainnet (bitcoin) network whereas other networks (testnet,
testnet4, signet, regtest) will set the same default ports they use for
non-Tor addresses (see above).
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 node's id.

  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.
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 '/torport=TORPORT' to select the external
tor binding. The result is that over tor your node is accessible by a port
defined by you and possibly 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 `HOSTNAME` or `TORIPADDRESS'`.

  If `HOSTNAME` was given that resolves to a local interface, the daemon
will bind to that interface.

* **bind-addr**=*\[ws:\]\[IPADDRESS\[:PORT\]\]|SOCKETPATH|HOSTNAME\[:PORT\]*

  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.

   The `ws:` prefix indicates to expect connections to use the
RFC-6455 WebSocket protocol instead of raw TCP/IP.  This is more
usable by web browsers directly, but often requires a reverse proxy
to speak TLS ("wss").

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

  If a HOSTNAME was given and `always-use-proxy` is not specified,
a DNS lookup may be done to resolve it and bind to a local interface (if found).

* **announce-addr**=*IPADDRESS\[:PORT\]|TORADDRESS.onion\[:PORT\]|dns:HOSTNAME\[: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.

  Since v23.058, the `dns:` prefix can be used to indicate that this hostname and port should be announced as a DNS hostname entry.  Please note that most mainnet nodes do not yet use, read or propagate this information correctly.

* **announce-addr-dns**=*BOOL* (deprecated in v23.08)

  When set to *true* (default is *false*), prefixes all `HOSTNAME` in **announce-addr** with `dns:`.

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

* **autoconnect-seeker-peers**=*NUMBER* (added in v24.11)

  Sets the number of peers to gossip with: if we don't have this many connections, we will try to connect to random peers until we do.  The default is 10.

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

* **tor-service-password**=*PASSWORD*

  Set a Tor control password, which may be needed for *autotor:* to
authenticate to the Tor control port.

* **clnrest-port**=*PORT* [plugin `clnrest`]

  Sets the REST server port to listen to (3010 is common).  If this is not specified, the clnrest plugin will be disabled.

* **clnrest-protocol**=*PROTOCOL* [plugin `clnrest`]

  Specifies the REST server protocol. Default is HTTPS.

* **clnrest-host**=*HOST* [plugin `clnrest`]

  Defines the REST server host. Default is 127.0.0.1.

* **clnrest-certs**=*PATH*  [plugin `clnrest`]

  Defines the path for HTTPS cert & key. Default path is same as RPC file path to utilize gRPC's client certificate. If it is missing at the configured location, new identity (`client.pem` and `client-key.pem`) will be generated.

* **clnrest-cors-origins**=*CORSORIGINS*  [plugin `clnrest`]

  Define multiple origins which are allowed to share resources on web pages to a domain different from the one that served the web page. Default is `*` which allows all origins.

* **clnrest-csp**=*CSPOLICY*  [plugin `clnrest`]

  Creates a whitelist of trusted content sources that can run on a webpage and helps mitigate the risk of attacks. Default CSP is `default-src 'self'; font-src 'self'; img-src 'self' data:; frame-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline';`.

* **clnrest-swagger-root**=*URL*  [plugin `clnrest`]

  Root url for Swagger UI. Default is `/`.

* **wss-bind-addr**=*\[IPADDRESS\[:PORT\]\]|SOCKETPATH|HOSTNAME\[:PORT\]* [plugin `wss-proxy`]

  Sets the WSS address. This option can be used multiple times to add more addresses.

* **wss-certs**=*PATH*  [plugin `wss-proxy`]

  Defines the path for WSS cert & key. Default path is same as RPC file path to utilize gRPC/clnrest's client certificate. If it is missing at the configured location, new identity (`client.pem` and `client-key.pem`) will be generated.

* **exposesecret-passphrase**=*passphrase*  [plugin `exposesecret`]

  Defines a passphrase which will let users extract the `hsm_secret` using the `exposesecret` command.  If this is not set, the `exposesecret` command always fails.


### 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 Core 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 file.

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

* **clear-plugins**

  This option clears all *plugin*, *important-plugin*, and *plugin-dir* options
preceding 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 Core 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`),
Core Lightning will also stop running.
This way, you can monitor crashes of important plugins by simply monitoring
if Core Lightning terminates.
Built-in plugins, which are installed with lightningd(8), are automatically
considered important.

### Experimental Options

Experimental options are subject to breakage between releases: they
are made available for advanced users who want to test proposed
features.

* **fetchinvoice-noconnect**

  Specifying this prevents `fetchinvoice`, `sendinvoice` and replying
to invoice request from trying to connect directly to the offering node as a last resort.

* **experimental-shutdown-wrong-funding**

  Specifying this allows the `wrong_funding` field in _shutdown: if a
remote node has opened a channel but claims it used the incorrect txid
(and the channel hasn't been used yet at all) this allows them to
negotiate a clean shutdown with the txid they offer ([#4421][pr4421]).

* **experimental-dual-fund**

  Specifying this enables support for the dual funding protocol ([bolt][bolt] #851),
allowing both parties to contribute funds to a channel. The decision
about whether to add funds or not to a proposed channel is handled
automatically by a plugin that implements the appropriate logic for
your needs. The default behavior is to not contribute funds.

* **experimental-splicing**

  Specifying this enables support for the splicing protocol ([bolt][bolt] #863),
allowing both parties to dynamically adjust the size a channel. These changes
can be built interactively using PSBT and combined with other channel actions
including dual fund, additional channel splices, or generic transaction activity.
The operations will be bundled into a single transaction. The channel will remain
active while awaiting splice confirmation, however you can only spend the smaller
of the prior channel balance and the new one.

* **experimental-lsps-client**

  Specifying this enables client side support for the lsps protocol
([blip][blip] #50). Core-Lightning only supports the lsps2 ([blip][blip] #52)
subprotocol describing the creation of just-in-time-channel (JIT-channels)
between a LSP and this client.

* **experimental-lsps2-service**

  Specifying this enables a LSP JIT-Channel service according to the lsps
protocol ([blip][blip] #52). It requires a LSP-Policy plugin to be available and
a *experimental-lsps2-promise-secret* to be set.

* **experimental-lsps2-promise-secret**=*promisesecret*

  Sets a `promisesecret` for the LSP JIT-Channel service. Is a 64-character hex
 string that acts as the secret for promises according to ([blip][blip] #52).
 Is required if *experimental-lsps2-service* is set.

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](mailto: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-setchannel(7) lightningd(8)
lightning-hsmtool(8)

RESOURCES
---------

Main web site: [https://github.com/ElementsProject/lightning](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.

[bolt]: https://github.com/lightning/bolts
[bolt12]: https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md
[pr4421]: https://github.com/ElementsProject/lightning/pull/4421
[blip]: https://github.com/lightning/blips
