|
| 1 | +LIGHTNINGD(8) |
| 2 | +============= |
| 3 | +:doctype: manpage |
| 4 | + |
| 5 | +NAME |
| 6 | +---- |
| 7 | +lightningd - Daemon for running a Lightning Network node |
| 8 | + |
| 9 | +SYNOPSIS |
| 10 | +-------- |
| 11 | +lightningd [--conf=<config-file>] ['OPTIONS']... |
| 12 | + |
| 13 | +DESCRIPTION |
| 14 | +----------- |
| 15 | +*lightningd* starts the C-Lightning daemon, which implements a |
| 16 | +standards-compliant Lightning Network node. |
| 17 | + |
| 18 | +CONFIGURATION OPTIONS |
| 19 | +--------------------- |
| 20 | +*--conf*='FILE':: |
| 21 | + Specify configuration file. |
| 22 | + If not an absolute path, will be relative from the lightning-dir |
| 23 | + location. |
| 24 | + Defaults to 'config'. |
| 25 | +*--lightning-dir*='DIR':: |
| 26 | + Set the directory for the C-Lightning daemon. |
| 27 | + Defaults to '$HOME/.lightning'. |
| 28 | + |
| 29 | +MORE OPTIONS |
| 30 | +------------ |
| 31 | +Command line options are mirrored as configuration options in the |
| 32 | +configuration file, so 'foo' in the configuration file simply |
| 33 | +becomes '--foo' on the command line, and 'foo=bar' becomes |
| 34 | +'--foo=bar'. |
| 35 | + |
| 36 | +See lightningd-config(5) for a comprehensive list of all |
| 37 | +available options. |
| 38 | + |
| 39 | +LOGGING AND COMMANDING C-LIGHTNING |
| 40 | +----------------------------- |
| 41 | +By default, C-Lightning will log to the standard output. |
| 42 | +To log to a specific file, use '--log-file=PATH'. |
| 43 | +Sending SIGHUP will cause C-Lightning to reopen this file, |
| 44 | +for example to do log rotation. |
| 45 | + |
| 46 | +C-Lightning will set up a Unix domain socket for receiving |
| 47 | +commands. |
| 48 | +By default this will be the file 'lightning-rpc' in your |
| 49 | +specified 'lightning-dir'. |
| 50 | +You can use lightning-cli(1) to send commands to C-Lightning |
| 51 | +once 'lightningd' has started; you need to match the |
| 52 | +'--lightning-dir' and '--rpc-file' options between them. |
| 53 | + |
| 54 | +Commands for C-Lightning are described in various manpages |
| 55 | +in section 7, with the common prefix 'lightning-'. |
| 56 | + |
| 57 | +QUICK START |
| 58 | +----------- |
| 59 | +First, decide on and create a directory for 'lightning-dir', |
| 60 | +or just use the default '$HOME/.lightning'. |
| 61 | +Then create a 'config' file in this directory containing your |
| 62 | +configuration. |
| 63 | + |
| 64 | +Your other main preparation would be to set up a mainnet Bitcoin |
| 65 | +fullnode, i.e. run a bitcoind(1) instance. |
| 66 | +The rest of this quick start guide will assume you are reckless |
| 67 | +and want to spend real funds on Lightning. |
| 68 | +Indicate 'network=bitcoin' in your 'config' file explicitly. |
| 69 | + |
| 70 | +C-Lightning needs to communicate with the Bitcoin Core RPC. |
| 71 | +You can set this up using 'bitcoin-datadir', 'bitcoin-rpcconnect', |
| 72 | +'bitcoin-rpcport', 'bitcoin-rpcuser', and 'bitcoin-rpcpassword' |
| 73 | +options in your 'config' file. |
| 74 | + |
| 75 | +Finally, just to keep yourself sane, decide on a log file name |
| 76 | +and indicate it using 'log-file=lightningd.log' in your 'config' file. |
| 77 | +You might be interested in viewing it periodically as you follow |
| 78 | +along on this guide. |
| 79 | + |
| 80 | +Once the *bitcoind* instance is running, start lightningd(8): |
| 81 | + |
| 82 | + $ lightningd --lightning-dir=$HOME/.lightning --daemon |
| 83 | + |
| 84 | +This starts *lightningd* in the background due to the '--daemon' |
| 85 | +option. |
| 86 | + |
| 87 | +Check if things are working: |
| 88 | + |
| 89 | + $ lightning-cli --lightning-dir=%HOME/.lightning help |
| 90 | + $ lightning-cli --lightning-dir=%HOME/.lightning getinfo |
| 91 | + |
| 92 | +The *getinfo* command in particular will return a 'blockheight' |
| 93 | +field, which indicates the block height to which *lightningd* |
| 94 | +has been synchronized to (this is separate from the block height |
| 95 | +that your *bitcoind* has been synchronized to, and will always |
| 96 | +lag behind *bitcoind*). |
| 97 | +You will have to wait until the 'blockheight' has reached the |
| 98 | +actual blockheight of the Bitcoin network. |
| 99 | + |
| 100 | +Before you can get funds offchain, you need to have some funds |
| 101 | +onchain owned by *lightningd* (which has a separate wallet from |
| 102 | +the *bitcoind* it connects to). |
| 103 | +Get an address for *lightningd* via lightning-newaddr(7) command |
| 104 | +as below ('--lightning-dir' option has been elided, specify it if |
| 105 | +you selected your own 'lightning-dir'): |
| 106 | + |
| 107 | + $ lightning-cli newaddr |
| 108 | + |
| 109 | +This will provide a native SegWit bech32 address. |
| 110 | +In case all your money is in services that do not support native |
| 111 | +SegWit and have to use P2SH-wrapped addresses, instead use: |
| 112 | + |
| 113 | + $ lightning-cli newaddr p2sh-segwit |
| 114 | + |
| 115 | +Transfer a small amount of onchain funds to the given address. |
| 116 | +Check the status of all your funds (onchain and on-Lightning) via |
| 117 | +lightning-listfunds(7): |
| 118 | + |
| 119 | + $ lightning-cli listfunds |
| 120 | + |
| 121 | +Now you need to look for an arbitrary Lightning node to connect to, |
| 122 | +which you can do by using dig(1) and querying 'lseed.bitcoinstats.com': |
| 123 | + |
| 124 | + $ dig lseed.bitcoinstats.com A |
| 125 | + |
| 126 | +This will give 25 IPv4 addresses, you can select any one of those. |
| 127 | +You will also need to learn the corresponding public key, which you can |
| 128 | +determine by searching the IP addrss on https://1ml.com/ . |
| 129 | +The public key is a long hex string, like so: |
| 130 | +'024772ee4fa461febcef09d5869e1238f932861f57be7a6633048514e3f56644a1'. |
| 131 | +(this example public key is not used as of this writing) |
| 132 | + |
| 133 | +After determining a public key, use lightning-connect(7) to |
| 134 | +connect to that public key: |
| 135 | + |
| 136 | + $ lightning-cli connect $PUBLICKEY |
| 137 | + |
| 138 | +Then open a channel to that node using lightning-fundchannel(7): |
| 139 | + |
| 140 | + $ lightning-cli fundchannel $PUBLICKEY $SATOSHI |
| 141 | + |
| 142 | +This will require that the funding transaction be confirmed before |
| 143 | +you can send funds over Lightning. |
| 144 | +To track this, use lightning-listpeers(7) and look at the 'state' |
| 145 | +of the channel: |
| 146 | + |
| 147 | + $ lightning-cli listpeers $PUBLICKEY |
| 148 | + |
| 149 | +The channel will initially start with a 'state' of |
| 150 | +'CHANNELD_AWAITING_LOCKIN'. |
| 151 | +You need to wait for the channel 'state' to become 'CHANNELD_NORMAL', |
| 152 | +meaning the funding transaction has been confirmed deeply. |
| 153 | + |
| 154 | +Once the channel 'state' is 'CHANNELD_NORMAL', you can start paying |
| 155 | +merchants over Lightning. |
| 156 | +Acquire a Lightning invoice from your favorite merchant, and use |
| 157 | +lightning-pay(7) to pay it: |
| 158 | + |
| 159 | + $ lightning-cli pay $INVOICE |
| 160 | + |
| 161 | +BUGS |
| 162 | +---- |
| 163 | +You should report bugs on our github issues page, and maybe submit a |
| 164 | +fix to gain our eternal gratitude! |
| 165 | + |
| 166 | +AUTHOR |
| 167 | +------ |
| 168 | +ZmnSCPxj < [email protected]> wrote the initial version of this |
| 169 | +man page, but many others did the hard work of actually implementing |
| 170 | +a standards-compliant Lightning Network node implementation. |
| 171 | + |
| 172 | +SEE ALSO |
| 173 | +-------- |
| 174 | +lightning-listconfigs(7), lightning-config(5), lightning-cli(1), |
| 175 | +lightning-newaddr(7), lightning-listfunds(7), lightning-connect(7), |
| 176 | +lightning-fundchannel(7), lightning-listpeers(7), lightning-pay(7) |
| 177 | + |
| 178 | +RESOURCES |
| 179 | +--------- |
| 180 | +Main web site: https://github.com/ElementsProject/lightning |
| 181 | + |
| 182 | +COPYING |
| 183 | +------- |
| 184 | +Note: the modules in the ccan/ directory have their own licenses, but |
| 185 | +the rest of the code is covered by the BSD-style MIT license. |
0 commit comments