mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-22 22:45:27 +01:00
Code Issues Projects Releases Wiki Activity
core-lightning/doc/lightningd.8.md
Rusty Russell 3c3f4731bd doc: format markdown correctly. 
There are no definition lists in Markdown, and lists get mangled if
they follow immediately: they need a line between them.

So use bullets for options, and use an indent so the text gets in the
line below.

Here's a before-and-after example:

```diff
 --- /tmp/after	2022-07-20 21:55:54.355487769 +0930
 +++ /tmp/after2	2022-07-20 21:58:17.305642576 +0930
 @@ -10,38 +10,71 @@
         lightning-cli sends commands to the lightning daemon.

  OPTIONS
 -       --lightning-dir=DIR Set the directory for the lightning daemon we're talking to; defaults to $HOME/.lightning.
 +       • --lightning-dir=DIR

 -       --conf=PATH Sets configuration file (default: lightning-dir/config ).
 +         Set the directory for the lightning daemon we're talking to; defaults to $HOME/.lightning.

 -       --network=network --mainnet --testnet --signet Sets network explicitly.
 +       • --conf=PATH

 -       --rpc-file=FILE Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
 +         Sets configuration file (default: lightning-dir/config ).

 -       --keywords/-k Use format key=value for parameters in any order
 +       • --network=network

 -       --order/-o Follow strictly the order of parameters for the command
 +       • --mainnet

 -       --json/-J Return result in JSON format (default unless help command, or result contains a format-hint field).
 +       • --testnet

 -       --raw/-R Return raw JSON directly as lightningd replies; this can be faster for large requests.
 +       • --signet

 -       --human-readable/-H Return result in human-readable output.
 +         Sets network explicitly.

 -       --flat/-F  Return  JSON result in flattened one-per-line output, e.g. { "help": [ { "command": "check" } ] } would become
 +       • --rpc-file=FILE
 +
 +         Named pipe to use to talk to lightning daemon: default is lightning-rpc in the lightning directory.
 +
 +       • --keywords/-k
 +
 +         Use format key=value for parameters in any order
 +
 +       • --order/-o
 +
 +         Follow strictly the order of parameters for the command
 +
 +       • --json/-J
 +
 +         Return result in JSON format (default unless help command, or result contains a format-hint field).
 +
 +       • --raw/-R
 +
 +         Return raw JSON directly as lightningd replies; this can be faster for large requests.
 +
 +       • --human-readable/-H
 +
 +         Return result in human-readable output.
 +
 +       • --flat/-F
 +
 +         Return  JSON  result  in  flattened  one-per-line  output,  e.g.  {  "help":  [ { "command": "check" } ] } would become
         help[0].command=check.  This is useful for simple scripts which want to find a  specific  output  field  without  parsing
         JSON.

 -       --notifications/-N=LEVEL  If  LEVEL is 'none', then never print out notifications.  Otherwise, print out notifications of
 -       LEVEL or above (one of io, debug, info (the default), unusual or broken: they are prefixed with # .
 +       • --notifications/-N=LEVEL
 +
 +         If  LEVEL  is 'none', then never print out notifications.  Otherwise, print out notifications of LEVEL or above (one of
 +         io, debug, info (the default), unusual or broken: they are prefixed with # .
 +
 +       • --help/-h
 +
 +         Pretty-print summary of options to standard output and exit.  The format can be changed using -F, -R, -J, -H etc.
 +
 +       • --version/-V

 -       --help/-h Pretty-print summary of options to standard output and exit.  The format can be changed using -F,  -R,  -J,  -H
 -       etc.
 +         Print version number to standard output and exit.

 -       --version/-V Print version number to standard output and exit.
 +       • allow-deprecated-apis=BOOL

 -       allow-deprecated-apis=BOOL Enable deprecated options. It defaults to true, but you should set it to false when testing to
 -       ensure that an upgrade won't break your configuration.
 +         Enable deprecated options. It defaults to true, but you should set it to false when testing to ensure that  an  upgrade
 +         won't break your configuration.

  COMMANDS
         lightning-cli simply uses the JSON RPC interface to talk to lightningd, and prints the results. Thus the commands  avail‐
 @@ -60,13 +93,13 @@
         this is not encouraged.

  EXAMPLES
 -       1.     List commands
 +       1.     List commands:

 -       lightning-cli help
 +              • lightning-cli help

 -       2.     Fund a 10k sat channel using uncomfirmed outputs
 +       2.     Fund a 10k sat channel using uncomfirmed outputs:

 -       lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0
 +              • lightning-cli --keywords fundchannel id=028f...ae7d amount=10000sat minconf=0

  BUGS
         This manpage documents how it should work, not how it does work. The pretty printing of results isn't pretty.
```

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-08 00:36:51 +03:00

6.7 KiB
Raw Blame History

lightningd -- Daemon for running a Lightning Network node

SYNOPSIS

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

DESCRIPTION

lightningd starts the Core Lightning daemon, which implements a standards-compliant Lightning Network node.

CONFIGURATION OPTIONS

  • --conf=FILE Specify configuration file. If not an absolute path, will be relative from the lightning-dir location. Defaults to config.

  • --lightning-dir=DIR Set the directory for the Core Lightning daemon. Defaults to $HOME/.lightning.

MORE OPTIONS

Command line options are mirrored as configuration options in the configuration file, so foo in the configuration file simply becomes --foo on the command line, and foo=bar becomes --foo=bar.

See lightningd-config(5) for a comprehensive list of all available options.

LOGGING AND COMMANDING CORE LIGHTNING

By default, Core Lightning will log to the standard output. To log to a specific file, use --log-file=PATH. Sending SIGHUP will cause Core Lightning to reopen this file, for example to do 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. You can use lightning-cli(1) to send commands to Core Lightning once lightningd has started; you need to match the --lightning-dir and --rpc-file options between them.

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

QUICK START

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 to set up a mainnet Bitcoin fullnode, i.e. run 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.

Core Lightning needs to communicate with the Bitcoin Core RPC. You can set this up using 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

The getinfo command in particular will return a blockheight field, which indicates the block height to which lightningd has been synchronized to (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 (which has a separate wallet from the bitcoind it connects to). Get an address for lightningd via lightning-newaddr(7) command as below (--lightning-dir option has been elided, specify it if you selected your own lightning-dir):

$ lightning-cli newaddr

This will provide a native SegWit bech32 address. In case all your money is in services that do not support native SegWit and have to use P2SH-wrapped addresses, instead use:

$ lightning-cli newaddr p2sh-segwit

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, 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 public key is a long hex string, like so: 024772ee4fa461febcef09d5869e1238f932861f57be7a6633048514e3f56644a1. (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.

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

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)

BUGS

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

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

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.