LIGHTNINGD(8)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

🌩️ LIGHTNINGD (lightningd) — the glow-up 🌩️

Hiii bestie, welcome to the lightningd(8) manual page ✨ (yep, section 8, system daemons — she's that girl 👑). This is the page for lightningd, and by the end of it you're gonna know exactly how to spin up a whole Lightning Network node. No cap. Let's go 💅

✨ NAME ✨

lightningd — the daemon for running a Lightning Network node 🦋

✨ SYNOPSIS ✨

lightningd [--conf=<config-file>] [OPTIONS]

✨ DESCRIPTION ✨

Okay so lightningd starts the Core Lightning daemon, and that daemon implements a standards-compliant Lightning Network node. That's it, that's the whole vibe check. Standards-compliant node, main character energy, periodt 🌈

✨ CONFIGURATION OPTIONS ✨

  • --conf=FILE — tells her which config file to use 📄. If FILE isn't an absolute path, it gets resolved relative to the lightning-dir location. Defaults to config.
  • --lightning-dir=DIR — sets the directory for the Core Lightning daemon 🎀. Defaults to $HOME/.lightning.

✨ MORE OPTIONS ✨

Not me about to explain the iconiest thing ever: command line options are mirrored as configuration options in the config file 🪞. So foo in the config file simply becomes --foo on the command line, and foo=bar becomes --foo=bar. Literally the same thing twice, iykyk.

Want the actual comprehensive list of all available options? Run, don't walk, to lightningd-config(5) 📚

✨ LOGGING AND COMMANDING CORE LIGHTNING ✨

By default, Core Lightning will log to the standard output 🌸. Wanna log to a specific file instead? Use --log-file=PATH. And here's the trick: sending SIGHUP will cause Core Lightning to reopen this file — iconic behaviour for doing log rotation 🔄.

Core Lightning will set up a Unix domain socket for receiving commands 🫶. By default this will be the file lightning-rpc in your specified lightning-dir. Once lightningd has started, you can use lightning-cli(1) (that's $ lightning-cli(1) in the original, ilysm) to send commands to Core Lightning — and heads up, you need to match the --lightning-dir and --rpc-file options between them, or they're not gonna talk 😭

Commands for Core Lightning are described in various manpages in section 7, with the common prefix lightning- 💜

✨ QUICK START ✨

Okay bestie, hands out of pockets, let's actually do this 🧚

First, decide on and create a directory for lightning-dir — or just use the default $HOME/.lightning. Then create a config file in this directory containing your configuration 📝.

Your other main preparation would be setting up a mainnet Bitcoin fullnode, i.e. running a bitcoind(1) instance. The rest of this quick start guide will assume you are reckless and want to spend real funds on Lightning — otherwise indicate network=testnet in your config file explicitly 🙈

Fr fr, read that again. Reckless. Real funds. Testnet option exists for a reason 💀

Core Lightning needs to communicate with the Bitcoin Core RPC. You can set this up using the bitcoin-datadir, bitcoin-rpcconnect, bitcoin-rpcport, bitcoin-rpcuser, and bitcoin-rpcpassword options in your config file 🔑

Finally, just to keep yourself sane, decide on a log file name and indicate it using log-file=lightningd.log in your config file. You might be interested in viewing it periodically as you follow along on this guide 👀

Once the bitcoind instance is running, start lightningd(8):

$ lightningd --lightning-dir=$HOME/.lightning --daemon

This starts lightningd in the background due to the --daemon option 🌙

Check if things are working:

$ $ lightning-cli --lightning-dir=$HOME/.lightning help
$ $ lightning-cli --lightning-dir=$HOME/.lightning getinfo

(Yes, the manpage literally prints $ $ — we keep the lore intact 💅)

The getinfo command in particular will return a blockheight field, which indicates the block height to which lightningd has been synchronized to. And just so you know — this is separate from the block height that your bitcoind has been synchronized to, and will always lag behind bitcoind 😴 You will have to wait until the blockheight has reached the actual blockheight of the Bitcoin network.

Before you can get funds offchain, you need to have some funds onchain owned by lightningd — and yes, she has a separate wallet from the bitcoind she connects to 👜 Get an address for lightningd via the lightning-newaddr(7) command as below (the --lightning-dir option has been elided here, so specify it if you selected your own lightning-dir):

$ $ lightning-cli newaddr

This will provide a native SegWit bech32 address ✨ Alternatively you can generate a taproot address with:

$ $ lightning-cli newaddr p2tr

Transfer a small amount of onchain funds to the given address. Check the status of all your funds (onchain and on-Lightning) via lightning-listfunds(7):

$ $ lightning-cli listfunds

Now you need to look for an arbitrary Lightning node to connect to, which you can do by using dig(1) and querying lseed.bitcoinstats.com:

$ dig lseed.bitcoinstats.com A

This will give 25 IPv4 addresses, and you can select any one of those 🔍 You will also need to learn the corresponding public key, which you can determine by searching the IP addrss on https://1ml.com/ (the manpage really does say "addrss", and honestly? she ate 🍓). The public key is a long hex string, like so: 024772ee4fa461febcef09d5869e1238f932861f57be7a6633048514e3f56644a1 — and note that this example public key is not used as of this writing 👑

After determining a public key, use lightning-connect(7) to connect to that public key at that IP:

$ $ lightning-cli connect $PUBLICKEY $IP

Then open a channel to that node using lightning-fundchannel(7):

$ $ lightning-cli fundchannel $PUBLICKEY $SATOSHI

This will require that the funding transaction be confirmed before you can send funds over Lightning ⚡ To track this, use lightning-listpeers(7) and look at the state of the channel:

$ $ lightning-cli listpeers $PUBLICKEY

The channel will initially start with a state of CHANNELD_AWAITING_LOCKIN ⏳ You need to wait for the channel state to become CHANNELD_NORMAL, meaning the funding transaction has been confirmed deeply. Patience is a virtue, bestie 😌

Once the channel state is CHANNELD_NORMAL, you can start paying merchants over Lightning 🛍️ Acquire a Lightning invoice from your favorite merchant, and use lightning-pay(7) to pay it:

$ $ lightning-cli pay $INVOICE

And that's the whole glow-up. Iconic.

✨ ERRORS CODE ✨

  • 1: Generic $ lightning-cli error
  • 10: Error executing subdaemons
  • 11: Error locking pidfile (often another lightningd running)
  • 20: Generic error related to HSM secret
  • 21: HSM secret is encrypted
  • 22: Bad password used to decrypt the HSM secred
  • 23: Error caused from the I/O operation during a HSM decryption/encryption operation
  • 30: Wallet database does not match (network or hsm secret)
Note: secred in entry 22 is straight from the original manpage. We do not fix. We do not touch. We respect the artifact 💀🫶

✨ BUGS ✨

You should report bugs on our github issues page, and maybe submit a fix to gain our eternal gratitude! 🥺👉👈 (That's literally what the manpage says. Eternal gratitude. She's real.)

✨ AUTHOR ✨

ZmnSCPxj ZmnSCPxj@protonmail.com wrote the initial version of this man page, but many others did the hard work of actually implementing a standards-compliant Lightning Network node implementation 🔥

✨ SEE ALSO ✨

lightningd-rpc(7), lightning-listconfigs(7), lightningd-config(5), $ lightning-cli(1), lightning-newaddr(7), lightning-listfunds(7), lightning-connect(7), lightning-fundchannel(7), lightning-listpeers(7), lightning-pay(7), 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 📜

Okay that's the whole page, bestie — you're officially learned 🎓💖 This was Core Lightning v26.06.9, section LIGHTNINGD(8) of the manual — go forth and slay your node 🌩️✨🦋

📦 where this page comes from