diff --git a/doc/Makefile b/doc/Makefile index 12bdf7809..e2ca90276 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,6 +5,7 @@ doc-wrongdir: $(MAKE) -C .. doc-all MANPAGES := doc/lightning-cli.1 \ + doc/lightningd.8 \ doc/lightningd-config.5 \ doc/lightning-autocleaninvoice.7 \ doc/lightning-check.7 \ diff --git a/doc/lightningd-config.5 b/doc/lightningd-config.5 index 7fd2312af..da57fa74b 100644 --- a/doc/lightningd-config.5 +++ b/doc/lightningd-config.5 @@ -2,12 +2,12 @@ .\" Title: lightningd-config .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 08/02/2019 +.\" Date: 08/04/2019 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "LIGHTNINGD\-CONFIG" "5" "08/02/2019" "\ \&" "\ \&" +.TH "LIGHTNINGD\-CONFIG" "5" "08/04/2019" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -164,7 +164,7 @@ Prefix for log lines: this can be customized if you want to merge logs with mult .PP \fBlog\-file\fR=\fIPATH\fR .RS 4 -Log to this file instead of stdout\&. Sending lightningd(1) SIGHUP will cause it to reopen this file (useful for log rotation)\&. +Log to this file instead of stdout\&. Sending lightningd(8) SIGHUP will cause it to reopen this file (useful for log rotation)\&. .RE .PP \fBrpc\-file\fR=\fIPATH\fR @@ -201,12 +201,12 @@ Up to 32 UTF\-8 characters to tag your node\&. Completely silly, since anyone ca .PP \fBfee\-base\fR=\fIMILLISATOSHI\fR .RS 4 -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 lightningd\-setchannelfee(7)\&. +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\-setchannelfee(7)\&. .RE .PP \fBfee\-per\-satoshi\fR=\fIMILLIONTHS\fR .RS 4 -Default: 10 (0\&.001%)\&. This is the proportional fee to charge for every payment which passes through\&. As percentages are too coarse, it\(cqs 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 lightningd\-setchannelfee(7)\&. +Default: 10 (0\&.001%)\&. This is the proportional fee to charge for every payment which passes through\&. As percentages are too coarse, it\(cqs 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\-setchannelfee(7)\&. .RE .PP \fBmin\-capacity\-sat\fR=\fISATOSHI\fR @@ -505,7 +505,7 @@ You should report bugs on our github issues page, and maybe submit a fix to gain Rusty Russell wrote this man page, and much of the configuration language, but many others did the hard work of actually implementing these options\&. .SH "SEE ALSO" .sp -lightning\-listconfigs(7) lightningd\-setchannelfee(7) +lightning\-listconfigs(7) lightning\-setchannelfee(7) lightningd(8) .SH "RESOURCES" .sp Main web site: https://github\&.com/ElementsProject/lightning diff --git a/doc/lightningd-config.5.txt b/doc/lightningd-config.5.txt index 71d17191b..83ff02b46 100644 --- a/doc/lightningd-config.5.txt +++ b/doc/lightningd-config.5.txt @@ -118,7 +118,7 @@ Lightning daemon options multiple daemons. *log-file*='PATH':: - Log to this file instead of stdout. Sending lightningd(1) SIGHUP will cause + Log to this file instead of stdout. Sending lightningd(8) SIGHUP will cause it to reopen this file (useful for log rotation). *rpc-file*='PATH':: @@ -151,14 +151,14 @@ Lightning node customization options 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 - lightningd-setchannelfee(7). + lightning-setchannelfee(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 lightningd-setchannelfee(7). + existing channels, use the RPC call lightning-setchannelfee(7). *min-capacity-sat*='SATOSHI':: Default: 10000. This value defines the minimal effective channel capacity @@ -366,7 +366,8 @@ of actually implementing these options. SEE ALSO -------- -lightning-listconfigs(7) lightningd-setchannelfee(7) +lightning-listconfigs(7) lightning-setchannelfee(7) +lightningd(8) RESOURCES --------- diff --git a/doc/lightningd.8 b/doc/lightningd.8 new file mode 100644 index 000000000..e69de29bb diff --git a/doc/lightningd.8.txt b/doc/lightningd.8.txt new file mode 100644 index 000000000..70cfdb3a2 --- /dev/null +++ b/doc/lightningd.8.txt @@ -0,0 +1,185 @@ +LIGHTNINGD(8) +============= +:doctype: manpage + +NAME +---- +lightningd - Daemon for running a Lightning Network node + +SYNOPSIS +-------- +lightningd [--conf=] ['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 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.