-
Notifications
You must be signed in to change notification settings - Fork 1k
doc/lightningd.8.txt: Initial manpage for lightningd itself. #2899
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
rustyrussell
merged 2 commits into
ElementsProject:master
from
ZmnSCPxj:lightningd-manpage
Aug 9, 2019
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Empty file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| LIGHTNINGD(8) | ||
| ============= | ||
| :doctype: manpage | ||
|
|
||
| NAME | ||
| ---- | ||
| lightningd - Daemon for running a Lightning Network node | ||
|
|
||
| SYNOPSIS | ||
| -------- | ||
| lightningd [--conf=<config-file>] ['OPTIONS']... | ||
|
|
||
| DESCRIPTION | ||
| ----------- | ||
| *lightningd* starts the C-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 C-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 C-LIGHTNING | ||
| ----------------------------- | ||
| By default, C-Lightning will log to the standard output. | ||
| To log to a specific file, use '--log-file=PATH'. | ||
| Sending SIGHUP will cause C-Lightning to reopen this file, | ||
| for example to do log rotation. | ||
|
|
||
| C-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 C-Lightning | ||
| once 'lightningd' has started; you need to match the | ||
| '--lightning-dir' and '--rpc-file' options between them. | ||
|
|
||
| Commands for C-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. | ||
| Indicate 'network=bitcoin' in your 'config' file explicitly. | ||
|
|
||
| C-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: | ||
|
|
||
| $ lightning-cli connect $PUBLICKEY | ||
|
|
||
| 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 | ||
|
|
||
| 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), lightning-config(5), lightning-cli(1), | ||
| lightning-newaddr(7), lightning-listfunds(7), lightning-connect(7), | ||
| lightning-fundchannel(7), lightning-listpeers(7), lightning-pay(7) | ||
|
|
||
| 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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if we should recommend the
helpmeplugin at this point. It does things like connect to nodes on the network for you, and suggest things.But that might have to wait until it's more mature?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If it does not come standard with a C-Lightning release, it is hard to recommend in the C-Lightning manpage. I am already wary about suggesting
digandhttps://1ml.combut could not find an easier way to get to some node, but at least those are common tools that can be easily acquired.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed. Let's add a bootstrap script.