LIGHTNINGD-CONFIG(5)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

🌸 NAME 🌸

lightningd-config (manual section 5) — the Lightning daemon configuration file. Yes bestie, it’s the config brain cell for lightningd 💖

✨ SYNOPSIS ✨

~/.lightning/config

💖 DESCRIPTION 💖

Okay so when lightningd(8) starts up, it usually reads a general configuration file first — default $HOME/.lightning/config — and then a network-specific configuration file — default $HOME/.lightning/bitcoin/config. You can change this: see --conf and --lightning-dir.

Some configuration options are marked dynamic, and those 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 instead. periodt ✨

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. literally a config-file generator, slay 💅

🎀 OPTIONS 🎀

🧸 General options 🧸

  • developer — This enables developer mode, allowing developer options and commands to be used. It also disables 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. chaotic little icon behavior 😭
  • 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 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: (yes, the source really says the heading twice — iconic in a chaotic way 💀)

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

...

So like, if you're a legacy bestie and you already have an encrypted hsm_secret that you made with the deprecated encrypted-hsm option? It keeps working. Seamlessly. No drama, no migration arc, it just vibes. 💖

And for the new mnemonic-based secrets: your passphrase becomes part of the seed derivation process exactly as specified in BIP39, which is giving extra security factor, honestly. The mnemonic words alone are not sufficient to derive the seed without the passphrase. Periodt. 🔐

If you've got an unencrypted legacy hsm_secret and you wanna encrypt it, or you just need to manage your HSM secrets generally, go see lightning-hsmtool(8). She'll sort you out. 🫶

Note: this option replaces the deprecated encrypted-hsm option. Old one's retired, new one ate. 💅
  • grpc-host=HOST [plugin cln-grpc] — picks the GRPC server host. Default is 127.0.0.1.
  • grpc-port=portnum [plugin cln-grpc] — the port number the GRPC plugin listens on for incoming connections. Default is 9736.
  • grpc-msg-buffer-size=number [plugin cln-grpc] — the size of the buffer the GRPC plugin uses. This buffer stores notifications between receiving them from lightningd and forwarding them over grpc. Heads up: if a buffer overflow happens, some notifications will not be delivered. 😭

🌸 Lightning node customization options 🌸

  • recover=mnemonic — restores 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 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. Main character aesthetic only. 🎀
  • 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 at 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, up to a maximum of 1000000perkw (4000 sat/vB). This may result in a channel which cannot be closed, should fees increase, but makes 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).
Okay so lowkey this one is a lil scary — read the "channel which cannot be closed" part again, bestie. 💀
  • 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 an 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. And note: this 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 network's 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. No cap. 🗣️
  • 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. She's deprecated but she's still iconic. ⭐
  • 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 multiple 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). Yes, the original sentence is missing a "have to be"-ish clause, we're not fixing it, we're just telling you the deal. 💀
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 💜

  • payment-fronting-node=nodeid — always use this nodeid as the entry point when we generate invoices or offers: currently, the node must be a neighbor we have a channel with. For BOLT11 invoices we will use a routehint with the alias for the short channel id to provide limited privacy (we still reveal our node id). For BOLT12 invoices and offers, we provide a blinded path from the node to us which provides better privacy. This can be specified multiple times for multiple fronting nodes. Lowkey obsessed with that BOLT12 privacy glow-up. ✨
  • disable-mpp [plugin pay]
  • Disable the multi-part payment sending support in the pay plugin. By default MPP support is enabled, but it can be desirable to disable it in situations in which each payment should result in a single HTLC being forwarded in the network. one payment, one HTLC, no splitting 💅
  • invoices-onchain-fallback — adds a (taproot) fallback address to invoices produced by the invoice command, so those invoices can also be paid onchain. dual-threat invoice, we love to see it ✨
  • xpay-handle-pay=BOOL [plugin xpay, dynamic] — setting this makes xpay intercept simple pay commands (default false). sneaky but iconic 🫶
  • 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. ngl the parenthetical is a whole mood 😭
  • xpay-user-layer=name [plugin xpay] — specify the name of a layer xpay shall use always for every payment. This is specially useful when combined with xpay-handle-pay since the layers parameter is not available in the pay interface. This can be specified multiple times to add more layers. stack 'em like scrunchies 🎀
  • 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. bestie that is a THREAT not a feature 💀
  • askrene-max-threads=NUMBER [plugin askrene, dynamic] — 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. (CPUS. yes. we're keeping it. it's canon now 🙈)
  • bkpr-currency=name [plugin bookkeeper, dynamic] — the name is an ISO-4217 name (e.g. USD), which will be passed to currencyrate to fetch the exchange rate for that currency on each bookkeeper event. Setting name to the empty string is equivalent to not setting it. fiat girlies rise 🌸
  • bwatch-poll-interval=MILLISECONDS [plugin bwatch] — delay between polls for new blocks from bitcoind (default: 30000). patience is a virtue ig ⭐
  • experimental-bwatch [plugin bwatch] — enable the experimental bwatch chain watcher. Without this, the plugin stays loaded but does not poll bitcoind or process watches. it's giving "I'm here but I'm not doing anything" energy 😭

🌐 Networking options 🌐

Okay so this is the part where your node decides where it lives on the internet, bestie. Listen up 🫶

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). defaults carrying the whole team fr fr ✨

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. yes "an new". we're not touching it. it's vintage 💅

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! no take-backs, no training wheels, main character energy only 👑

  • 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. write those numbers down, there WILL be a quiz 🦋

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. 64 bytes in, first 32 bytes matter. the math is mathing 🧚

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. it just knows where it belongs 🎀

  • 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 /. quiet listener vibes 🤫

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"). browser-friendly era 🌈

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). no safety net, bestie — you're on your own 🙈

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. v23.058. that's the version. that's what it says. we don't question the ancients 💀

  • announce-addr-dns=BOOL (deprecated in v23.08) — when set to true (default is false), prefixes all HOSTNAME in announce-addr with dns:. deprecated but still invited to the party 🫶
  • 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. airplane mode but make it crypto ✈️
  • 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. making friends by brute force, iconic 🌸
  • 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. the default-default 💅
  • 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. privacy queen behavior 👑
  • disable-dns — disable the DNS bootstrapping mechanism to find a node by its node ID.
  • message-padding=BOOL — if set to true, connectd will send extra bytes to peers to make messages uniform length. Some implementations don't accept these extra bytes, and our detection of them is not always reliable, so this option defaults to false. padding: great idea, chaotic execution 😭
  • tor-service-password=PASSWORD — set a Tor control password, which may be needed for autotor: to authenticate to the Tor control port. secret password, do not share 🤫
  • 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. no port, no plugin. harsh but fair 🎀
  • 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. localhost said "this is my house" 🏠
  • 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. new identity, who dis 💅
  • 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. everyone's invited, apparently 💀
  • 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';. copy that string EXACTLY, semicolons and all, or it won't slay 🌈
  • clnrest-swagger-root=URL [plugin clnrest] — root url for Swagger UI. Default is /. swagger stays swaggering ✨
  • 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. more addresses, more problems, more vibes 🦋
  • wss-certs=PATH [plugin wss-proxy]
  • (carrying on from the WSS one above 🫶) — sets the path for the WSS cert & key. Default path is the same as the RPC file path, so it can use gRPC/clnrest's client certificate. If it's not there at the configured location, a whole new identity gets generated for you: client.pem and client-key.pem. ✨
  • exposesecret-passphrase=passphrase [plugin exposesecret] — defines a passphrase that lets users extract the hsm_secret using the exposesecret command. If you don't set this, the exposesecret command always fails. no cap, it's just never gonna work 💀
  • currencyrate-add-source=NAME,URL,MEMBER [plugin cln-currencyrate] — adds a price source for the cln-currencyrate plugin. The form is NAME,URL,MEMBERS, where URL and MEMBERS can both contain {currency} and {currency_lc} — those get substituted with the upper-case and lower-case currency names respectively, bestie. MEMBERS is how you deconstruct the result: for example, if the result looks like {"USD": {"last_trade": 12456.79}} then MEMBERS would be USD,last_trade. And if you need to deconstruct an array, specify its position with its index, starting at 0. (added in v26.04) 🌸

The default sources are, and yes these are all of them:

  • currencyrate-disable-source=NAME [plugin cln-currencyrate] — disables the cln-currencyrate source with this name. that's it, that's the whole vibe 🦋 (added in v26.04)

🔌 Lightning Plugins 🔌

so lightningd(8) supports plugins, and they're lowkey iconic: they hand you extra configuration options and JSON-RPC methods, all depending on which plugin it is. Some come supplied by default (usually chillin' in libexec/c-lightning/plugins/). And if a plugins directory exists under lightning-dir, that gets searched for plugins too, along with any immediate subdirectories. You can also point at extra paths yourself:

  • plugin=PATH — specify a plugin to run as part of Core Lightning. You can drop this multiple times to add multiple plugins. 💅 Note that unless the plugins themselves specify ordering requirements for being called on various hooks, plugins get ordered by commandline first, then config file.
  • plugin-dir=DIRECTORY — specify a directory to look for plugins in; every executable file that doesn't contain punctuation (other than ., - or _) in DIRECTORY gets loaded. DIRECTORY must exist, and yeah, this can be specified multiple times to add multiple directories. The ordering of plugins within a directory is currently unspecified — chaos, honestly 🎀
  • clear-plugins — this one wipes all plugin, important-plugin, and plugin-dir options that came before it, including the default built-in plugin directory. You can still add plugin-dir, plugin, and important-plugin options after it and they'll work totally normally. clean slate energy ✨
  • disable-plugin=PLUGIN — if PLUGIN contains a /, then plugins with the same path as PLUGIN won't be loaded at startup. Otherwise, no plugin with that base name gets loaded at startup, whatever directory it's chillin' in. This option is genuinely useful for disabling a single plugin inside a directory. And you can still explicitly load plugins that you've disabled, using lightning-plugin(7) start. sneaky, but allowed 😌
  • important-plugin=PLUGIN — specify a plugin to run as part of Core Lightning. This can be specified multiple times to add multiple plugins. The plugins you set here are considered so important that if the plugin stops for any reason (including via lightning-plugin(7) stop), Core Lightning will also stop running. That's the whole point, bestie: you can monitor crashes of important plugins by simply monitoring whether Core Lightning terminates. 👑 Built-in plugins that ship installed with lightningd(8) are automatically considered important. main character plugins only, fr fr.

🧪 Experimental Options 🧪

⚠️ Heads up: experimental options are subject to breakage between releases. They're out here for advanced users who wanna test proposed features. You've been warned 💀
  • 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 at all yet), this lets them negotiate a clean shutdown with the txid they offer (#4421).
  • experimental-dual-fund — specifying this enables support for the dual funding protocol (bolt #851), letting both parties 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 #863), letting both parties 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 get bundled into a single transaction. The channel stays active while awaiting splice confirmation — however, you can only spend the smaller of the prior channel balance and the new one. 🙈
🫶 (deprecated in v26.04)
  • experimental-lsps-client — specifying this enables client-side support for the lsps protocol (blip #50). Core-Lightning only supports the lsps2 (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 #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. It's a 64-character hex string that acts as the secret for promises according to (blip #52). It's 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! (literally eternal. we will never stop being grateful 🫶)

✍️ AUTHOR ✍️

Rusty Russell rusty@rustcorp.com.au wrote this man page, and much of the configuration language — but many others did the hard work of actually implementing these options. team effort, slay 💜

👀 SEE ALSO 👀

lightning-listconfigs(7) lightning-setchannel(7) lightningd(8) lightning-hsmtool(8)

🌐 RESOURCES 🌐

Main web site: https://github.com/ElementsProject/lightning

📜 COPYING 📜

Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD-style MIT license.

and that's the whole page, bestie!! 🎀 This masterpiece is from Core Lightning v26.06.9 and if you ever need to cite it, the fancy official name is LIGHTNINGD-CONFIG(5). go forth and configure responsibly 💅✨

📦 where this page comes from