Bitcoin Core

In this section we'll install the Bitcoin node software, Bitcoin Core. We'll install the various files in accordance with the Filesystem Hierarchy Standard (FHS) discussed earlier.

These are the files and directories we'll be using for Bitcoin Core:

/etc/bitcoin.conf                     Configuration
/etc/systemd/system/bitcoind.service  System service
/var/lib/bitcoin                      Blockchain and data
/var/log/bitcoin                      Logs
/etc/logrotate.d/bitcoin              Log rotation
/usr/local/bin                        Symlinks to binaries
/usr/local/lib/bitcoin                Installed Bitcoin Core versions

From the Terminal program on a Mac or Linux computer, or PowerShell on Windows, connect to your Bitcoin node:

ssh nelson@bitcoin-node.local

Become superuser.

su -

Create the installation directory

Create a bitcoin directory under /usr/local/lib. This is where the Bitcoin Core binaries will be installed:

cd /usr/local/lib
mkdir bitcoin
cd bitcoin

Download Bitcoin Core

We'll download the Bitcoin Core binaries directly into the installation directory using wget.

From your web browser, go to:

https://bitcoincore.org

Select RELEASES from the menu bar, then select the latest release. At the time of writing this is Bitcoin Core 31.0.

Near the top of the page you'll find the binaries for the various supported platforms.

Locate the Linux package appropriate for your computer.

This workshop uses the following package as an example:

bitcoin-31.0-x86_64-linux-gnu.tar.gz

Right-click the package name and select Copy Link (or your browser's equivalent).

Download the package using wget, pasting the copied link after the command:

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

Download the SHA256SUMS and SHA256SUMS.asc files in the same way:

wget https://bitcoincore.org/bin/bitcoin-core-31.0/SHA256SUMS
wget https://bitcoincore.org/bin/bitcoin-core-31.0/SHA256SUMS.asc

The checksum and signature files will be used to verify the downloaded package.

Verify the download

The Bitcoin Core binaries have been digitally signed by a number of the Bitcoin Core builders. We need their public keys before we can verify the download.

You'll need both git and gpg installed.

Download the builder keys:

git clone https://github.com/bitcoin-core/guix.sigs

Import the keys into GPG:

gpg --import guix.sigs/builder-keys/*

Verify the signature on the checksum file:

gpg --verify SHA256SUMS.asc SHA256SUMS

You should see Good signature from... for a number of the Bitcoin Core builders.

You can safely ignore the warning:

WARNING: The key's User ID is not certified with a trusted signature!

This simply means the signing key is not part of your personal GPG web of trust. It does not mean the signature is invalid.

Now verify the downloaded package:

sha256sum --ignore-missing -c SHA256SUMS

You should see:

bitcoin-31.0-x86_64-linux-gnu.tar.gz: OK

Unpack the archive

Extract the downloaded package:

tar -xzf bitcoin-31.0-x86_64-linux-gnu.tar.gz

The downloaded archive and checksum files are no longer required:

rm bitcoin-31.0-x86_64-linux-gnu.tar.gz
rm SHA256SUMS
rm SHA256SUMS.asc

Enter the newly created directory:

cd bitcoin-31.0

Rename the supplied configuration file. We'll create our own configuration under /etc:

mv bitcoin.conf bitcoin.conf.example

Create a Bitcoin user

Create a dedicated system user for Bitcoin Core:

useradd \
--system \
--home-dir /var/lib/bitcoin \
--create-home \
--shell /usr/sbin/nologin \
bitcoin

Create the configuration file

Create the Bitcoin Core configuration file:

nano /etc/bitcoin.conf

Paste the following into the file:

server=1
txindex=1

datadir=/var/lib/bitcoin/
debuglogfile=/var/log/bitcoin/debug.log

dbcache=2048
maxconnections=40
maxuploadtarget=500

# Networking
listen=1

#Comment out Tor settings until it's installed.
#proxy=127.0.0.1:9050
#listenonion=1

rpcbind=127.0.0.1
rpcallowip=127.0.0.1

whitelist=download@127.0.0.1

rpcthreads=16
rpcworkqueue=256
#debug=net
#debug=rpc
#debug=validation
#debug=1

Set the correct permissions:

chmod 644 /etc/bitcoin.conf

Create symbolic links

Create symbolic links to the binaries:

ln -sf /usr/local/lib/bitcoin/bitcoin-31.0/bin/bitcoind /usr/local/bin/bitcoind
ln -sf /usr/local/lib/bitcoin/bitcoin-31.0/bin/bitcoin-cli /usr/local/bin/bitcoin-cli
ln -sf /usr/local/lib/bitcoin/bitcoin-31.0/bin/bitcoin-cli /usr/local/bin/bitcoin-wallet

Verify the installation:

bitcoind --version

Configure logging

Create the Bitcoin Core log directory:

mkdir -p /var/log/bitcoin
chown bitcoin:bitcoin /var/log/bitcoin

Create the logrotate configuration file:

nano /etc/logrotate.d/bitcoin

Paste the following into the file:

/var/log/bitcoin/debug.log {
    su bitcoin bitcoin
    weekly
    rotate 12
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
    create 640 bitcoin bitcoin
}

Set the correct permissions:

chmod 644 /etc/logrotate.d/bitcoin

Test the installation

Before creating a system service, test that Bitcoin Core starts correctly:

su -s /bin/bash bitcoin -c "bitcoind -conf=/etc/bitcoin.conf"

If the configuration is correct, Bitcoin Core will start and begin initialising.

Stop the test by pressing Ctrl+C.

Create the system service

Create the systemd service file:

nano /etc/systemd/system/bitcoind.service

Paste the following into the file:

[Unit]
Description=Bitcoin daemon
After=network-online.target
Wants=network-online.target

[Service]
User=bitcoin
Group=bitcoin

ExecStart=/usr/local/bin/bitcoind -conf=/etc/bitcoin.conf
ExecStop=/usr/local/bin/bitcoin-cli -conf=/etc/bitcoin.conf stop

Type=exec
Restart=on-failure
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

Set the correct permissions:

chmod 644 /etc/systemd/system/bitcoind.service

Tell systemd to reload its configuration.

systemctl daemon-reload

Enable Bitcoin Core to start automatically when the computer boots:

systemctl enable bitcoind

Start the service:

systemctl start bitcoind

Check its status:

systemctl status bitcoind

Query the node

You can communicate with Bitcoin Core using bitcoin-cli.

For example:

bitcoin-cli -conf=/etc/bitcoin.conf getblockchaininfo
bitcoin-cli -conf=/etc/bitcoin.conf getnetworkinfo

getblockchaininfo returns information about the blockchain, including whether the node is performing the Initial Block Download (IBD) and its current verification progress.

Generate the RPC Credentials

The dashboard requires an RPC username and password to communicate with Bitcoin Core. We'll use the rpcauth.py script supplied with Bitcoin Core to generate the required credentials.

Change to the Bitcoin Core installation directory.

cd /usr/local/lib/bitcoin

Change into the installed Bitcoin Core version directory.

cd bitcoin-31.0

Change to the rpcauth directory.

cd share/rpcauth

Run the credential generation script using dashboard as the username.

./rpcauth.py dashboard

The output will look something like the following, with different numbers.

String to be appended to bitcoin.conf:
rpcauth=dashboard:bfa06a4bbbaf45da9090eaec3f7cd64e$1730aed923b7a68a0a21fde864931f33d3d1d75a2951b889f97e08e4458ab1bd
Your password:
7ISeVmRcES2j9TcbYLnZgfVz3z9xYsTzmSodRhS8dRY

Copy the first line into /etc/bitcoin.conf, then restart bitcoind:

systemctl restart bitcoind

Open the dashboard configuration file:

nano /srv/www/dashboard/config/bitcoin-rpc.php

Replace RPC-PASSWORD-HERE with the above password. The dashboard now has the authority to query Bitcoin Core.

Install the manual pages (optional)

Bitcoin Core includes Linux manual pages for its command-line programs. Once installed, you can view the built-in documentation directly from the terminal without needing an internet connection.

Copy the manual pages into the standard system location:

cd /usr/local/lib/bitcoin
cd bitcoin-31.0 (or whatever your version directory is)
cd share/man
cp -r man1 /usr/local/share/man/
mandb

The mandb command rebuilds the system's manual page database so the new pages can be found by the man command.

You can then view the documentation for the Bitcoin Core programs:

man bitcoind

man bitcoin-cli

man bitcoin-wallet

Press Space to move forward one page, b to move back, and q to quit.

Port Forwarding

If you want to accept incoming requests from bitcoin node peers you will need to enable port forwarding on your router. Forward port 8333 to the ip address of your node.

Next steps

You now have a fully functioning Bitcoin node.

Bitcoin Core will begin downloading and validating the blockchain. Depending on your hardware and internet connection, this may take several days.

Once the Initial Block Download has completed, you'll be ready to install an Electrum server and, later, a Lightning node.