Skip to content

Instantly share code, notes, and snippets.

@bretton
Last active November 15, 2022 18:53
  • Star 70 You must be signed in to star a gist
  • Fork 16 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save bretton/0b22a0503a9eba09df86a23f3d625c13 to your computer and use it in GitHub Desktop.
Detailed guide to installing LND and Bitcoind on Ubuntu 16.04 LTS for Mainnet

Intro

This guide is specific to getting LND 0.5-beta and Bitcoind running on Ubuntu 16.04 LTS for mainnet. It is aging rapidly and includes steps not necessary on newer versions of LND. As of April 2021 it is very out of date for bitcoind. As of December 2021 it is outdated for LND too.

Original installation guide:

This guide is broken into the following sections:

  • Install bitcoind and set to start automatically
  • Install development tools and dependancies
  • Install lnd, setup a config file, fund and open channels
  • Install supervisor to automatically start lnd and optionally send email on failures

Advance warnings:

  • The bitcoind portion of this guide can take several days to sync
  • The lnd portion of this guide can take several hours to sync

Install bitcoind

Published instructions

https://bitcoin.org/en/full-node#linux-instructions

Compiling yourself

if you'd prefer to compile bitcoind yourself, please refer to https://gist.github.com/itoonx/95aec9a3b4da01fd1fd724dffc056963
and take note of sudo apt install libzmq3-dev and ./configure ... --with-zmq --enable-zmq

Installation

First add the repository:

sudo apt-add-repository ppa:bitcoin/bitcoin

You will be prompted for your user password. Provide it to continue, and press enter when prompted.

Run the update process:

sudo apt-get update

Then proceed with installing bitcoind as follows:

sudo apt-get install bitcoind

Setup your .bitcoin/bitcoin.conf file, there are samples at:

http://manpages.ubuntu.com/manpages/precise/man5/bitcoin.conf.5.html
https://github.com/bitcoin/bitcoin/blob/0.16/contrib/debian/examples/bitcoin.conf

Simplest version might be as follows:

server=1
txindex=1
daemon=1
externalip=X.X.X.X
maxconnections=10
rpcuser=REPLACEME
rpcpassword=REPLACEME
minrelaytxfee=0.00000000
incrementalrelayfee=0.00000010
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333

Note: as of github master from 2018-08-10 onwards you need different ports for each zmq config option, setup in bitcoin.conf

Start bitcoind to initiate sync, and be sure to take a look at https://en.bitcoin.it/wiki/Running_Bitcoin

bitcoind

You can monitor the progress in the logs:

tail $HOME/.bitcoin/debug.log

Important: The bitcoind sync process can take 3 to 5 days to complete!

(Optional) You can monitor progress with the following:

Install jq to trim the json:

sudo apt-get install jq

Get the current block count and run it through jq:

curl -s https://api.smartbit.com.au/v1/blockchain/blocks |jq -r -c .blocks[0].height

or if your system requires it:

curl -s https://api.smartbit.com.au/v1/blockchain/blocks |jq -r -c '.blocks[0].height'

Compare the result to the output of:

bitcoin-cli getblockcount

Alternatively, combine both of these into a convenient one-liner expression:

echo `bitcoin-cli getblockcount 2>&1`/`curl -s https://api.smartbit.com.au/v1/blockchain/blocks |jq -r -c .blocks[0].height 2>/dev/null`

or if your system requires it:

echo `bitcoin-cli getblockcount 2>&1`/`curl -s https://api.smartbit.com.au/v1/blockchain/blocks |jq -r -c '.blocks[0].height' 2>/dev/null`

If the output values are the same, then your bitcoind node is fully synced and you can proceed with lnd installation.

Setting up bitcoind to start automatically

To setup bitcoind to start automatically, we'll borrow the systemd setup from the following guide:

Adapted from sources

First make sure bitcoind is fully synced, then stop it with:

bitcoin-cli stop

Add & edit the systemd configuration file:

sudo nano /etc/systemd/system/bitcoind.service

Add in the following text, making sure to replace all instances of USERNAME with your username, or the applicable username bitcoind is being run as:

[Unit]
Description=Bitcoin daemon
After=network.target

[Service]
User=USERNAME
Group=USERNAME
Type=forking
PIDFile=/home/USERNAME/.bitcoin/bitcoind.pid
ExecStart=/usr/bin/bitcoind -conf=/home/USERNAME/.bitcoin/bitcoin.conf -pid=/home/USERNAME/.bitcoin/bitcoind.pid
KillMode=process
Restart=always
TimeoutSec=120
RestartSec=30

[Install]
WantedBy=multi-user.target

Enable the systemd setup with the following commands:

sudo systemctl enable bitcoind
sudo systemctl start bitcoind

Check it's working properly with:

sudo systemctl status bitcoind

bitcoind should start automatically from here on, and restart if it fails.

Next we need to install go, then lnd.

Install Go

The lnd install guide refers to golang-1.10-go, but Ubuntu 16.04 LTS currently has golang-1.9-go. To install the latest go using snap instead:

sudo snap install --classic go

On success you will see the result:

go 1.10 from 'mwhudson' installed

or

go 1.11.2 from Michael Hudson-Doyle (mwhudson) installed

Create a 'go' directory in your home directory:

mkdir go

Set go paths, this can be done in .profile (which reads .bashrc) or directly in .bashrc:

You might notice some difference between ssh sessions and local terminal sessions with .profile so for the purpose of this guide we'll use .bashrc as the results are the same for both types of session

nano .bashrc

Add to the end:

export GOPATH=$HOME/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin

Important: the snap install of go will automatically set the GOROOT variable. It's no longer necessary to set this yourself, unless using apt-get install for older version of go prior to 1.11.

Logout and log back in to reread variables, or you can type:

source .bashrc

Check variables with:

go env

And if you see output, go is setup correctly.

Install build tools

lnd is now using dep to manage dependancies, and dep has some additional requirements for development tools, so make sure you have the build-essential package installed:

sudo apt-get install build-essential
sudo apt-get install git-core

Install dep:

go get -u github.com/golang/dep/cmd/dep

Install LND

Install lnd by cloning the source and then the build commands as follows, according to the The LND Install Guide:

git clone https://github.com/lightningnetwork/lnd
cd lnd
make install

and use the following for checking out a release, the preferred way of installing LND:

git clone https://github.com/lightningnetwork/lnd
cd lnd
git checkout v0.x.x
make install

Important: this next step requires bitcoind be fully synced!

Run lnd for first run as follows, it will take a while to catch up and perform its own sync:

lnd --bitcoin.active --bitcoin.mainnet --debuglevel=debug --bitcoin.node=bitcoind --bitcoind.rpcuser=REPLACEME --bitcoind.rpcpass=REPLACEME --externalip=X.X.X.X --bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332 --bitcoind.zmqpubrawtx=tcp://127.0.0.1:28333

But before the sync actually starts, in another terminal window you will need to create a wallet, store the recovery key, and then issue the unlock command.

To create a wallet run:

lncli create

An example of the output is as follows. Please ensure you have a strong password with minimum 8 characters, and mix of uppercase and lowercase:

Input wallet password: ********
Confirm wallet password: ********

Do you have an existing cipher seed mnemonic you want to use? (Enter y/n): n

Your cipher seed can optionally be encrypted.
Input your passphrase you wish to encrypt it (or press enter to proceed without a cipher seed passphrase): ********
Confirm cipher seed passphrase: ********

Generating fresh cipher seed...

!!!YOU MUST WRITE DOWN THIS SEED TO BE ABLE TO RESTORE THE WALLET!!!

------------------BEGIN LND CIPHER SEED------------------
 1. one        2. two        3. three        4. four 
 5. five       6. six        7. seven        8. eight
 9. nine      10. ten       11. eleven      12. twelve 
13. thirteen  14. fourteen  15. fifteen     16. sixteen
17. seventeen 18. eighteen  19. nineteen    20. twenty
21. twentyone 22. twentytwo 23. twentythree 24. twentfour
------------------END LND CIPHER SEED--------------------

Copy and paste the cipher seed and store it securely somehow, such a secure note in a password manager, or printed to paper and locked in a safe, or similar.

You will now have to unlock the wallet you just created so lnd can proceed with the initial sync:

lncli unlock

Once sync is complete, you can <ctrl-c> the lnd process, and proceed with editing a config file so you can start lnd with fewer flags on next launch.

Create and edit $HOME/.lnd/lnd.conf from

https://github.com/lightningnetwork/lnd/blob/master/sample-lnd.conf

A very simple version might be as follows, you can add more from the info in the sample config later:

[Application Options]
; set external IP if not using NAT
externalip=YOURIP
; set node alias (seen in explorers)
alias=SET-YOUR-ALIAS

[Bitcoin]
bitcoin.active=1
bitcoin.mainnet=1
bitcoin.node=bitcoind

[Bitcoind]
bitcoind.rpcuser=REPLACE
bitcoind.rpcpass=REPLACE
bitcoind.zmqpubrawblock=tcp://127.0.0.1:28332
bitcoind.zmqpubrawtx=tcp://127.0.0.1:28333

Note: as of github master from 2018-08-10 onwards you need different ports for each zmq config option, and no longer use bitcoind.zmqpath option.

Thereafter you can start lnd without flags, or using supervisor (see below) or some other option like systemd:

lnd

You monitor the log file in the logs directory under $HOME/.lnd/logs/bitcoin/mainnet/lnd.log

To verify lnd is operational, open another terminal window or session and try the following:

lncli getinfo
lncli getnetworkinfo
lncli describegraph

Setup a wallet to deposit some bitcoin:

lncli newaddress p2wkh

This will produce a Bech32 format address, which is native segwit address format, with lower fees in fee calculations for opening/closing channels.

If you have troubles depositing to bech32 address from places like earn.com or exchanges which don't yet support segwit addressing, you can also use lncli newaddress np2wkh to get a different format address that looks more like a traditional multisig address, but won't be able to take advantage of segwit fees benefits.

Make the deposit and check progress with:

lncli walletbalance 

A confirmed a balance means the deposit is complete and ready for opening channels.

To open your first channel(s) it may be useful to find active nodes. You can do this by browsing the node directory at various explorers such as https://www.robtex.com/lightning/node/ or https://1ml.com/node or you can open channels with the following:

* bitrefill: 024a2e265cd66066b78a788ae615acdc84b5b0dec9efac36d7ac87513015eaf6ed@lnd.bitrefill.com:9735
* yalls: 03e50492eab4107a773141bb419e107bda3de3d55652e6e1a41225f06a0bbf2d56@mainnet-lnd.yalls.org:9735
* guide author: 02262bbc21c171bc91a1d6bbf89571c95873849b9a60d3ea9671b777d852d39ecd@197.155.6.118:9735

Open a channel by first connecting, then opening a channel as follows:

lncli connect pubkey@ip:port
lncli openchannel --node_key=<pubkey> --local_amt=<amount>

Helpful hint:

if mSATs, satoshis, bits, mBTC are confusing, consider installing this useful calculator https://github.com/jb55/bcalc

Verify pending & open channels using:

lncli pendingchannels
lncli listchannels

Setup Supervisor to run LND automatically

supervisor is one way to start lnd automatically, and automatically restart if it fails.

First exit any running lnd session, and proceed through the following steps:

First install supervisor:

sudo apt-get install supervisor

Then setup the configuration file, sudo access will be required:

cd /etc/supervisor/conf.d
sudo nano lnd.conf

Edit lnd.conf and add the following:

[program:lnd]
user=REPLACE-WITH-YOUR-USERNAME
command=/home/USERNAME/go/bin/lnd --configfile=/home/USERNAME/.lnd/lnd.conf
startretries=999999999999999999999999999
autostart=true
autorestart=true

Reload supervisor:

sudo supervisorctl reload

You can monitor the log files by tailing them in the relevant directories in your home directory for lnd, or in /var/log/supervisor/ with sudo access.

Important: If lnd restarts via supervisor for some reason, you will need to unlock your wallet again for the node to go live.

lncli unlock

Email notification of supervisor restart

If you wish to be notified by email when supervisor restarts a process, you can install the superlance plugin:

sudo apt-get install python-pip
sudo -H pip install superlance

Edit supervisor's config file:

sudo nano /etc/supervisor/supervisord.conf

Add the following, changing the email address to your email address:

[eventlistener:crashmail]
command=/usr/local/bin/crashmail -p lnd -m your@email.address
events=PROCESS_STATE

This should be followed by updating supervisor, which will also restart lnd, and add the event notifier you've configured:

sudo supervisorctl update

So be sure to unlock your wallet again:

lncli unlock

When a process exits you will now get a notification sent via email and can login to unlock the wallet and take your node fully online again.

Next: Incoming Liquidity

You might be interested in How to get Inbound Liquidity on LN

That's it, happy channeling. If you liked this guide and got it working, please consider leaving a tip

@jason-me
Copy link

jason-me commented Sep 2, 2018

Nice write-up!

@Engelberg
Copy link

This looks great. Would be very interested to see a version of this that includes running the node through TOR.

@paolot0rr3s
Copy link

@ctrlbreak-
Copy link

It isn't explicitly mentioned in the steps above, but:

sudo apt install snapd

will install snap on Ubuntu...

@ctrlbreak-
Copy link

ctrlbreak- commented Dec 22, 2018

Also, something in the guide isn't working... I get to the step:

go env

... and it claims go is not installed:

"
go env
The program 'go' is currently not installed. You can install it by typing:
sudo apt install golang-go
"

EDIT: Reboot seems to have fixed it.

@ctrlbreak-
Copy link

... should also point out that if compiling bitcoin yourself, you'll need:

sudo apt install libzmq3-dev

and ensure the configuration for bitcoin prior to making includes:

./configure ... --with-zmq --enable-zmq

@bretton
Copy link
Author

bretton commented Jan 4, 2019

@inpay
Copy link

inpay commented Jan 7, 2019

LND also requires installation of
go get github.com/urfave/cli

@sauravtom
Copy link

Is there a docker setup for this somewhere?

@inpay
Copy link

inpay commented Jan 9, 2019

  1. Make sure you're using at least go1.11.4
  2. Remove special characters from RPC username and password

@molxyz
Copy link

molxyz commented Jan 27, 2019

LND also requires installation of
go get github.com/urfave/cli

@inpay You don't have to do this manually, when you compile LND it will install the CLI for you.
Instruction how to compile and install LND is here: https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md#installing-lnd .
make && make install will create and install the executables for lnd and lncli.

@bretton
Copy link
Author

bretton commented Feb 16, 2019

@molxyz

This is the current link for bitcoin.conf examples:

updated

@obarat
Copy link

obarat commented Feb 18, 2019

I had to format your command to fetch the latest block from smartbit:

~ curl -s https://api.smartbit.com.au/v1/blockchain/blocks |jq -r -c .blocks[0].height

zsh: no matches found: .blocks[0].height~ curl -s https://api.smartbit.com.au/v1/blockchain/blocks |jq -r -c '.blocks[0].height'

563536

@firepol
Copy link

firepol commented Feb 19, 2019

Thanks for this write up.

Concerning GO, instead of installing it via snap, I prefer to use PPA.

If you installed via snap (and you don't need snap and installed it just for bitcoin) to get rid of it:

sudo snap remove go
sudo apt remove snapd

Then, to install it via apt (source, official: https://github.com/golang/go/wiki/Ubuntu):

sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt-get update
sudo apt-get install golang-go

@toschdev
Copy link

This helped me a lot setting up my first Lightning Node. Thanks!

@bretton
Copy link
Author

bretton commented Apr 12, 2019

@firepol - awesome, thanks!

@bretton
Copy link
Author

bretton commented Apr 12, 2019

@obarat - great stuff, updated

@gijswijs
Copy link

Great guide. I found one issue:
git is a requirement of the go get command. So before you can do

go get -u github.com/golang/dep/cmd/dep

you should install git:

sudo apt-get install git-core

@cgTabet
Copy link

cgTabet commented Mar 1, 2020

best guide I've found so far. Thanks!!

@bn185068
Copy link

bn185068 commented Dec 3, 2021

Unfortunately, it seems that these lines no longer work (or at least I can't get them to work)

go get -d github.com/lightningnetwork/lnd
cd $GOPATH/src/github.com/lightningnetwork/lnd
make && make install

According to lightningnetwork/lnd issue #5907, guggero recommends installing using the INSTALL.md installation instructions.

Other than that, this is the best guide I've found thus far!

@bretton
Copy link
Author

bretton commented Dec 4, 2021

Thanks @bn185068 - updated. The guide needs an overhaul for new Linux, Bitcoind and more.

@bn185068
Copy link

bn185068 commented Dec 4, 2021

@bretton you're welcome! I'm going through it now, so if I run into more snags, I'll post here.

@bn185068
Copy link

bn185068 commented Dec 4, 2021

Oh, also, the bitcoind installation no longer works.

sudo apt-add-repository ppa:bitcoin/bitcoin
sudo apt-get install bitcoind

I used

wget https://bitcoincore.org/bin/bitcoin-core-22.0/bitcoin-22.0-x86_64-linux-gnu.tar.gz
tar -xvf bitcoin-22.0-x86_64-linux-gnu.tar.gz

Then I copied all the binaries from bitcoin-22.0/bin/ into /usr/local/bin

sudo cp -R  ~/bitcoin-22.0/bin/* /usr/bin/

These links are dead:
http://manpages.ubuntu.com/manpages/precise/man5/bitcoin.conf.5.html
https://github.com/bitcoin/bitcoin/blob/0.16/contrib/debian/examples/bitcoin.conf

But you can customize a bitcoin.conf file here: https://jlopp.github.io/bitcoin-core-config-generator/
We're building on testnet, so I'm pasting my conf file for reference

# [chain]
# Test Network.
# Run this node on the Bitcoin Test Network. Equivalent to -chain=test
testnet=1

# [core]
# Only download and relay blocks - ignore unconfirmed transaction
blocksonly=1
# Imports blocks from external blk000??.dat file on startup. This option can be set multiple times with different file values.
loadblock=FILEPATH
# Assume that this block hash and its ancestors are valid. Skip their script verification (performance boost.) Set to 0 to verify all blocks. We recommend leaving value blank.
assumevalid=1
# Run in the background as a daemon and accept commands.
daemon=1

# [debug]
# Use smaller block files and lower minimum prune height for testing purposes.
fastprune=1

# [rpc]
# Accept command line and JSON-RPC commands.
server=1
# Accept public REST requests.
rest=1


# [Sections]
# Most options automatically apply to mainnet, testnet, and regtest networks.
# If you want to confine an option to just one network, you should add it in the relevant section.
# EXCEPTIONS: The options addnode, connect, port, bind, rpcport, rpcbind and wallet
# only apply to mainnet unless they appear in the appropriate section below.

# Options only for mainnet
[main]

# Options only for testnet
[test]
port=18333
rpcbind=127.0.0.1
rpcuser=USER
rpcpassword=PASSWORD
rpcallowip=127.0.0.1
rpcallowip=
rpcport=8332
# Options only for regtest
[regtest]

This conf will make the IBD very fast bc you're only downloading blocks (i.e. no unconfirmed txns) and assumevalid=1 assumes validity of blocks up to a certain point based on the bitcoind software. Finishes in minutes, but only use it for testing purposes!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment