# Installation ### Preliminaries In order to work with [`lnd`](https://github.com/lightningnetwork/lnd), the following build dependencies are required: * **Go:** `lnd` is written in Go. To install, run one of the following commands: **Note**: The minimum version of Go supported is Go 1.9. We recommend that users use the latest version of Go, which at the time of writing is [`1.10`](https://blog.golang.org/go1.10). On Linux: ``` sudo apt-get install golang-1.10-go ``` > Note that golang-1.10-go puts binaries in /usr/lib/go-1.8/bin. If you want them on your PATH, you need to make that change yourself. On Mac OS X ``` brew install go ``` Alternatively, one can download the pre-compiled binaries hosted on the [golang download page](https://golang.org/dl/). If one seeks to install from source, then more detailed installation instructions can be found [here](http://golang.org/doc/install). At this point, you should set your `$GOPATH` environment variable, which represents the path to your workspace. By default, `$GOPATH` is set to `~/go`. You will also need to add `$GOPATH/bin` to your `PATH`. This ensures that your shell will be able to detect the binaries you install. ```bash export GOPATH=~/gocode export PATH=$PATH:$GOPATH/bin ``` We recommend placing the above in your .bashrc or in a setup script so that you can avoid typing this every time you open a new terminal window. * **dep:** This project uses `dep` to manage dependencies as well as to provide *reproducible builds*. To install `dep`, execute the following command (assumes you already have Go properly installed): ``` go get -u github.com/golang/dep/cmd/dep ``` ### Installing lnd With the preliminary steps completed, to install `lnd`, `lncli`, and all related dependencies run the following commands: ``` git clone https://github.com/lightningnetwork/lnd $GOPATH/src/github.com/lightningnetwork/lnd cd $GOPATH/src/github.com/lightningnetwork/lnd dep ensure go install . ./cmd/... ``` **Updating** To update your version of `lnd` to the latest version run the following commands: ``` cd $GOPATH/src/github.com/lightningnetwork/lnd git pull && dep ensure go install . ./cmd/... ``` **Tests** To check that `lnd` was installed properly run the following command: ``` go install; go test -v -p 1 $(go list ./... | grep -v '/vendor/') ``` ### Installing btcd `lnd` currently requires the [roasbeef](https://github.com/roasbeef/btcd) fork of `btcd` due to neutrino additions that are not yet available in the master branch. To install, run the following commands: Install **btcd**: (must be from roasbeef fork, not from btcsuite) ``` go get -u github.com/Masterminds/glide git clone https://github.com/roasbeef/btcd $GOPATH/src/github.com/roasbeef/btcd cd $GOPATH/src/github.com/roasbeef/btcd glide install go install . ./cmd/... ``` ### Starting btcd Running the following command will create `rpc.cert` and default `btcd.conf`. ``` btcd --testnet --txindex --rpcuser=REPLACEME --rpcpass=REPLACEME ``` If you want to use `lnd` on testnet, `btcd` needs to first fully sync the testnet blockchain. Depending on your hardware, this may take up to a few hours. (NOTE: It may take several minutes to find segwit-enabled peers.) While `btcd` is syncing you can check on its progress using btcd's `getinfo` RPC command: ``` btcctl --testnet --rpcuser=REPLACEME --rpcpass=REPLACEME getinfo { "version": 120000, "protocolversion": 70002, "blocks": 1114996, "timeoffset": 0, "connections": 7, "proxy": "", "difficulty": 422570.58270815, "testnet": true, "relayfee": 0.00001, "errors": "" } ``` Additionally, you can monitor btcd's logs to track its syncing progress in real time. You can test your `btcd` node's connectivity using the `getpeerinfo` command: ``` btcctl --testnet --rpcuser=REPLACEME --rpcpass=REPLACEME getpeerinfo | more ``` ### lnd #### Simnet vs. Testnet Development If you are doing local development, such as for the tutorial, you'll want to start both `btcd` and `lnd` in the `simnet` mode. Simnet is similar to regtest in that you'll be able to instantly mine blocks as needed to test `lnd` locally. In order to start either daemon in the `simnet` mode use `simnet` instead of `testnet`, adding the `--bitcoin.simnet` flag instead of the `--bitcoin.testnet` flag. Another relevant command line flag for local testing of new `lnd` developments is the `--debughtlc` flag. When starting `lnd` with this flag, it'll be able to automatically settle a special type of HTLC sent to it. This means that you won't need to manually insert invoices in order to test payment connectivity. To send this "special" HTLC type, include the `--debugsend` command at the end of your `sendpayment` commands. There are currently two primary ways to run `lnd`: one requires a local `btcd` instance with the RPC service exposed, and the other uses a fully integrated light client powered by [neutrino](https://github.com/lightninglabs/neutrino). #### Running lnd in Light Client Mode In order to run `lnd` in its light client mode, you'll need to locate a full-node which is capable of serving this new light client mode. A [BIP draft](https://github.com/Roasbeef/bips/blob/master/gcs_light_client.mediawiki) exists, and will be finalized in the near future, but for now you'll need to be running `roasbeef`'s fork of btcd. A public instance of such a node can be found at `faucet.lightning.community`. To run lnd in neutrino mode, run `lnd` with the following arguments, (swapping in `--bitcoin.simnet` if needed), and also your own `btcd` node if available: ``` lnd --bitcoin.active --bitcoin.testnet --debuglevel=debug --bitcoin.node=neutrino --neutrino.connect=faucet.lightning.community ``` #### Running lnd using the btcd backend If you are on testnet, run this command after `btcd` has finished syncing. Otherwise, replace `--bitcoin.testnet` with `--bitcoin.simnet`. If you are installing `lnd` in preparation for the [tutorial](http://dev.lightning.community/tutorial), you may skip this step. ``` lnd --bitcoin.active --bitcoin.testnet --debuglevel=debug --btcd.rpcuser=kek --btcd.rpcpass=kek --externalip=X.X.X.X ``` #### Running lnd using the bitcoind or litecoind backend The configuration for bitcoind and litecoind are nearly identical, the following steps can be mirrored with loss of generality to enable a litecoind backend. Setup will be described in regards to `bitciond`, but note that `lnd` uses a distinct `litecoin.node=litecoind` argument and analogous subconfigurations prefixed by `litecoind`. To configure your bitcoind backend for use with lnd, first complete and verify the following: - The `bitcoind` instance must be configured with `--txindex` just like `btcd` above - Additionally, since `lnd` uses [ZeroMQ](https://github.com/bitcoin/bitcoin/blob/master/doc/zmq.md) to interface with `bitcoind`, *your `bitcoind` installation must be compiled with ZMQ*. If you installed it from source, this is likely the case, but if you installed it via Homebrew in the past it may not be included ([this has now been fixed](https://github.com/Homebrew/homebrew-core/pull/23088) in the latest Homebrew recipe for bitcoin) - Configure the `bitcoind` instance for ZMQ with `--zmqpubrawblock` and `--zmqpubrawtx` (the latter is optional but allows you to see unconfirmed transactions in your wallet). They must be combined in the same ZMQ socket address (e.g. `--zmqpubrawblock=tcp://127.0.0.1:28332` and `--zmqpubrawtx=tcp://127.0.0.1:28332`). - Start `bitcoind` running against testnet, and let it complete a full sync with the testnet chain (alternatively, use `--bitcoind.regtest` instead). Here's a sample `bitcoin.conf` for use with lnd: ``` testnet=1 txindex=1 server=1 daemon=1 zmqpubrawblock=tcp://127.0.0.1:18501 zmqpubrawtx=tcp://127.0.0.1:18501 ``` Once all of the above is complete, and you've confirmed `bitcoind` is fully updated with the latest blocks on testnet, run the command below to launch `lnd` with `bitcoind` as your backend (as with `bitcoind`, you can create an `lnd.conf` to save these options, more info on that is described further below): ``` lnd --bitcoin.active --bitcoin.testnet --debuglevel=debug --bitcoin.node=bitcoind --bitcoind.rpcuser=REPLACEME --bitcoind.rpcpass=REPLACEME --bitcoind.zmqpath=tcp://127.0.0.1:28332 --externalip=X.X.X.X ``` *NOTE:* - The auth parameters `rpcuser` and `rpcpass` parameters can typically be determined by `lnd` for a `bitcoind` instance running under the same user, including when using cookie auth. In this case, you can exclude them from the `lnd` options entirely. - If you DO choose to explicitly pass the auth parameters in your `lnd.conf` or command line options for `lnd` (`bitcoind.rpcuser` and `bitcoind.rpcpass` as shown in example command above), you must also specify the `bitcoind.zmqpath` option. Otherwise, `lnd` will attempt to get the configuration from your `bitcoin.conf`. - You must ensure the same address (including port) is used for the `bitcoind.zmqpath` option passed to `lnd` as for the `zmqpubrawblock` and `zmqpubrawtx` passed in the `bitcoind` options. #### Disabling Wallet Encryption To disable encryption of the wallet files, pass the `--noencryptwallet` argument to `lnd`. Obviously beware the security implications of running an unencrypted wallet - this argument must only be used for testing purposes. #### Macaroons `lnd`'s authentication system is called **macaroons**, which are decentralized bearer credentials allowing for delegation, attenuation, and other cool features. You can learn more about them in Alex Akselrod's [writeup on Github](https://github.com/lightningnetwork/lnd/issues/20). Running `lnd` for the first time will by default generate the `admin.macaroon`, `read_only.macaroon`, and `macaroons.db` files that are used to authenticate into `lnd`. They will be stored in the default `lnd` data directory. Note that if you specified an alternative data directory (via the `--datadir` argument), you will have to additionally pass the updated location of the `admin.macaroon` file into `lncli` using the `--macaroonpath` argument. To disable macaroons for testing, pass the `--no-macaroons` flag into *both* `lnd` and `lncli`. #### Network Reachability If you'd like to signal to other nodes on the network that you'll accept incoming channels (as peers need to connect inbound to initiate a channel funding workflow), then the `--externalip` flag should be set to your publicly reachable IP address. # Creating an lnd.conf (Optional) Optionally, if you'd like to have a persistent configuration between `lnd` launches, allowing you to simply type `lnd --bitcoin.testnet --bitcoin.active` at the command line, you can create an `lnd.conf`. **On MacOS, located at:** `/Users/[username]/Library/Application Support/Lnd/lnd.conf` **On Linux, located at:** `~/.lnd/lnd.conf` Here's a sample `lnd.conf` for `btcd` to get you started: ``` [Application Options] debuglevel=trace debughtlc=true maxpendingchannels=10 [Bitcoin] bitcoin.active=1 ``` Notice the `[Bitcoin]` section. This section houses the parameters for the Bitcoin chain. `lnd` also supports Litecoin testnet4 (but not both BTC and LTC at the same time), so when working with Litecoin be sure to set to parameters for Litecoin accordingly. For node configuration, the sections are called `[Btcd]`, `[Bitcoind]`, `[Neutrino]`, `[Ltcd]`, and `[Litecoind]` depending on which chain and node type you're using. # Accurate as of: - _roasbeef/btcd commit:_ `f8c02aff4e7a807ba0c1349e2db03695d8e790e8` - _roasbeef/btcutil commit:_ `a259eaf2ec1b54653cdd67848a41867f280797ee` - _lightningnetwork/lnd commit:_ `08de2becf8d77fae192205172c4fb17bb09bd0dbf49e64aa323b2fcbf9fe2a35`