How To Run a Bitcoin Full Node over Tor on an Ubuntu (Linux) Virtual Machine (updated 2020)

A step-by-step guide to getting a Bitcoin Full Node running on your computer — no previous experience required!

Full Nodes are Bitcoin’s nervous system!

This article updated in April 2020 with latest info and corrections, including VirtualBox 6.1, Ubuntu Server 18.04.4 LTS, and Bitcoin Core 19.1

Have you thought about experimenting with a full bitcoin server but are concerned about privacy or messing something up on your main OS? Then read on… This article will walk you through all the steps needed to run a Bitcoin node over the TOR security protocol within a virtual machine. You won’t have to worry about corrupting your main/host OS, and this will provide a low-risk Bitcoin node playground to experiment. This guide is made with the Microsoft Windows version of VirtualBox, but the process is nearly identical on MacOS and Linux once you’ve installed VirtualBox for your platform.

Because I know how difficult it can be to find up-to-date guides for this kind of setup, I am planning to update this guide regularly with new releases of Bitcoin Core, VirtualBox, and Ubuntu. Hopefully this will ensure that curious tinkerers will always have an accurate and up-to-date guide available.

Please see References at the bottom — I couldn’t have compiled this guide without them.

Part Zero — Overview

In this guide, we will be accomplishing four main tasks:

Setting up a VirtualBox virtual machine host Installing and configuring the latest stable, long-term-support version of Ubuntu Server within that virtual machine host Installing and configuring a Bitcoin Core (bitcoind) Full Node Configuring bitcoind to run over the Tor network (this protects your privacy while conveniently avoiding the need to modify any home router settings to allow incoming Bitcoin network traffic)

Part One — Prerequisites

Because a true full node requires downloading and storing the entire history of the Bitcoin blockchain, you will need to ensure you have approximately 320GB (as of April 2020) of free hard disk space, ideally closer to 350–400GB. While you can perform what’s known as “pruning” to trim the amount of disk space used after the initial blockchain download, I will not be covering that here.

The size of the blockchain also means that depending on your network connection, the initial download/sync could take hours, days…or even longer. Be patient!

Part Two— Setting up the VirtualBox platform

VirtualBox is a free, open source program for running virtual machines on your computer. To download, visit https://www.virtualbox.org/

Download the latest version (currently 6.1) for your platform, which for me (on Windows 10) is VirtualBox-6.1.4–136177-Win.exe

Launch the exe installer and simply accept all defaults. When this completes, we are ready to install Ubuntu!

Part Three — Configuring our Ubuntu Linux server virtual machine

Ubuntu is one of the most popular distributions of the Linux operating system and is free to download and use. In this guide, I’ll be using what’s known as the LTS (Long-term Support) version, which is supported and provided security updates for five years.

This is great for a “headless” (no GUI) server where no fancy graphics or latest-and-greatest consumer applications are needed. That being said, you could use their newer, more frequently updated version. Just be aware that things might break… But Bitcoin is known for its code stability, so it makes sense to run it on an OS that is also known for its code stability!

To start, download the latest LTS version (currently 18.04.4LTS) from Ubuntu’s website: https://ubuntu.com/download/server/thank-you?version=18.04.4&architecture=amd64

The file name for this version is ubuntu-18.04.4-live-server-amd64.iso

Once the ISO (disc image) file has downloaded, start Virtual Box. You’ll be presented with main interface, which is rather blank at the moment. So let’s add a new VM:

From the top menu, Click Machine →New…

Give the VM a name, such as Ubuntu Server

In Type select Linux

In Version select Ubuntu (64-bit) — Click Next >

In the Memory size dialog, choose as much memory as you can without negatively impacting your ability to otherwise use your computer while VirtualBox is running. I have 16GB of RAM on my host computer, so I will choose ~4GB here. The more memory you can allocate, the better, as the initial Bitcoin blockchain download/sync is memory intensive. You can always scale this back (or up) later as needed. — Click Next >

On the Hard disk dialog, select Create a virtual hard disk now — Click Create

On the Hard disk file type dialog, leave VDI selected — Click Next >

On the Storage on physical hard disk dialog, leave Dynamically allocated selected — Click Next >

On the File location and size dialog, you’ll want to choose at least 350GB, preferably 400GB. Note that VirtualBox won’t consume this space immediately, but will grow the virtual disk in size as needed, up to that limit. — Click Create

Setup will complete, and you’ll see a new entry in the left-hand column listing your new Virtual Machine. Now we need to get it up and running!

Part Four — Installing Ubuntu Linux on our new virtual machine disk

Right-click the new Virtual Machine in the left column and Choose Start →Normal Start from the main VirtualBox menu. Alternatively, click the large green Start button on the main button bar.

You will be prompted for a start-up disk. Choose the Ubuntu .iso file we downloaded earlier, then click Start.

The Ubuntu installer will launch. After a brief wait, you’ll be greeted with the Welcome screen. Because this is a headless server installer, there is no traditional mouse-based graphical interface.

To navigate the text-based installer, you must use the arrow keys to move among selections, the Tab key to jump to confirmation buttons (yes/no/done/continue), and the Enter key to select. You can also use the arrow keys to scroll all the way down to the confirmation buttons, but Tab is much faster.

Page 1 — Welcome Screen

Choose your preferred language (reminder — navigate with the arrow keys, then press Enter when your language is highlighted)

*** Installer Update ***

You may be prompted to update the installer at this point. If so, choose Update to the new installer and then proceed.

Page 2 — Keyboard configuration

Select your keyboard layout and variant (default is usually fine — you can just press Enter)

Page 3 — Network connections

Your network settings should be automatically identified and a local IP address generated. If it does not, resolution is far beyond the scope of this guide — you’ll need to seek assistance.

Page 4 — Configure proxy

Leave blank

Page 5 — Configure Ubuntu archive mirror

Leave default Mirror selected

Page 6a — Guided storage configuration

Leave Use an Entire Disk selected

Page 6b

Leave the default file system devices selected

Page 6c

Choose Continue on the Confirm destructive action dialog (remember, we are in a Virtual Machine, so this is NOT wiping anything on your host/main OS!)

Page 7 — Profile Setup

Enter your name (or whatever you prefer), a name for the server, and a username and password. The username entered here will be the one we use to run the Bitcoind service itself. For this guide, I’ll be using core

Page 8 — SSH Setup

Leave the defaults selected (no openSSH server)

Page 9

Leave all Featured Server Snaps unselected

Page 10a — Installation complete!

The server will begin installation of packages. You’ll just need to wait until the install completes, usually just a few minutes

Page 10a — Installation complete!

Choose Reboot to restart your newly installed server.

Press Enter when prompted to Please remove the installation media (VirtualBox will choose the newly installed server instead of the .iso automatically)

The VM will reboot, and after a few minutes you’ll see the login prompt. Congratulations, your new server is ready! (You may need to press Enter once the boot messages stop — sometimes the login prompt won’t appear otherwise in the VM).

Before we proceed to the next section of this guide, we’ll want to make sure our server is up-to-date with the latest security and software updates.

To do so, login, then from the prompt type

sudo apt update && sudo apt upgrade

Enter your password when prompted, press Enter, and wait for everything to update. You should run the above command periodically to ensure your server is up-to-date with security patches!

Now we can get to the fun part: installing the Bitcoin-Core server, bitcoind!

Note: At this point you will likely want to install the VirtualBox Guest Additions for Ubuntu Server. This will enable better performance as well as additional features you may want in the future. Enabling this is outside the scope of this document. However, there is an excellent guide for doing so:

https://virtualzero.net/blog/how-to-install-virtualbox-guest-additions-in-ubuntu-server-18.04-lts

Part Five — Installing the Bitcoin Core server (bitcoind)

To install bitcoind, we’ll be downloading and compiling the source code for both bitcoin and the Berkeley Database it uses to store wallet info. Before we can do so, we’ll need to install some prerequisite software.

First we need to enable an additional software repository that contains some essential compilation tools (you’ll need to enter your password for most of the following commands):

sudo add-apt-repository universe

Additional packages will install. Once complete, we can install our other prerequisites:

sudo apt-get install build-essential autoconf libtool pkg-config libboost-all-dev libssl-dev libevent-dev doxygen libzmqpp-dev libdb++-dev

We are ready to install the BerkeleyDB database software that is required for Bitcoin’s wallet functionality. First we’ll use the wget command to download the software:

wget http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz

Next, we’ll verify that the download is authentic/has not been tampered with:

echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef db-4.8.30.NC.tar.gz' | sha256sum -c

If the output ends in “OK,” the file is safe! The next few commands will extract the software, set some environment variables, and configure, compile, and install it. Enter each command separately!

tar -xvf db-4.8.30.NC.tar.gz cd db-4.8.30.NC/build_unix

mkdir -p build BDB_PREFIX=$(pwd)/build ../dist/configure --disable-shared --enable-cxx --with-pic --prefix=$BDB_PREFIX make install

The last step will take a few minutes. When complete, we can — finally! — download, configure, compile, and install Bitcoin Core.

First, make sure you return to your Ubuntu home directory (that’s a tilde, usually on your keyboard to the left of the numeral 1):

cd ~

We’ll use the Git software versioning tool to download the Bitcoin source code and sync it to our VM:

Now we need to checkout the latest stable version (currently v0.19.1 — you can run git tag to list versions):

cd bitcoin git checkout v0.19.1 git status

The last command should report HEAD detached at followed by the version number you requested. We are ready to get the build scripts prepped for compiling the source:

./autogen.sh

A few minutes later, and we are ready to configure what options we want to compile into our Bitcoin build. For this article, we will not be using the Graphical User Interface (gui), so we can disable that. The other mysterious flags are used to tell the compiler where/how to use the Berkeley Database:

./configure CPPFLAGS="-I${BDB_PREFIX}/include/ -O2" LDFLAGS="-L${BDB_PREFIX}/lib/" --with-gui=no (NOTE the -O2 flag contains the letter “oh”, not the numeral zero!)

Finally, we are ready to compile! This step can take quite a long time depending on the speed of your system, so be patient — go make coffee!

make make check sudo make install

After you’ve finished your coffee, we can proceed with configuring Bitcoin to use Tor.

Part Six — Configuring Bitcoin to use Tor

Before we launch the Bitcoin Core server (bitcoind), we’ll need to create its configuration file to ensure that it downloads the full blockchain history (so we can directly inspect any transaction) and uses only Tor connections. By default, even if you have Tor installed and configured, bitcoind will still communicate with nodes over TCP — we have to explicitly tell it to only use TOR to protect our privacy:

cd ~ mkdir .bitcoin touch .bitcoin/bitcoin.conf echo "txindex=1" >> .bitcoin/bitcoin.conf echo "onlynet=onion" >> .bitcoin/bitcoin.conf

Note that if at a later time you determine bitcoind is using up too much throughput on your network, you can help reduce its usage by limiting how many other nodes it connects to at a time:

echo "maxconnections=20" >> .bitcoin/bitcoin.conf

Experiment with different numbers where I’ve used 20 above until you reach an acceptable level of network throughput.

Note that initial blockchain download takes a long time, but it takes even longer over Tor, as the Tor network is quite a bottleneck. You might consider allowing initial blockchain download directly over TCP (by putting a # in front of the Onlynet line to disable it). After that, you can proceed with enabling the Tor features below. Note that doing this will expose your external IP address to the network, however.

Now we need to install Tor, which is simple on Ubuntu:

sudo apt install tor

Ensure that the following lines are (anywhere) in the Tor configuration file — /usr/share/tor/tor-service-defaults-torrc:

ControlPort 9051

CookieAuthentication 1

CookieAuthFileGroupReadable 1

To view the default settings, use the command:

less /usr/share/tor/tor-service-defaults-torrc

If anyone of the above lines are missing, add them using the echo command as before, for example:

sudo sh -c "echo 'ControlPort 9051' >> /usr/share/tor/tor-service-defaults-torrc"

If you had to add any of the above lines, be sure to restart the Tor service:

sudo /etc/init.d/tor restart

In order to allow bitcoind access to the authentication that Tor uses, we have to add the user that runs bitcoind (the one you setup earlier while installing Ubuntu) to the Tor group (for me, I will put core where username is listed below, as that’s the user I setup earlier):

sudo usermod -a -G debian-tor username

Now be sure to logout and back in to make sure group membership is updated (can also just restart the VM if you like). Once that’s done, we are finally ready to launch Bitcoin over Tor!

bitcoind -daemon

You can use the following command to monitor progress:

tail -f ~/.bitcoin/debug.log

It may take several days (or more) to download and initialize the entire blockchain. Once that completes, your node will be fully operational and can serve blocks to other nodes on the Tor network. You’ll want to verify that IPv4 and IPv6 are set to “false” in the following command output to ensure you are operating ONLY over Tor:

bitcoin-cli getnetworkinfo

Once your node is fully synced and actively serving blocks to other nodes, you can run the following command to see if it’s doing so. If you see any “true” results, it’s working!

bitcoin-cli getpeerinfo | grep true

Feel free to ask any questions or post about problems in the comments. Thanks for reading!

References

https://medium.com/@lopp/how-to-run-bitcoin-as-a-tor-hidden-service-on-ubuntu-cff52d543756

https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch03.asciidoc

https://www.reddit.com/r/Bitcoin/comments/4y7nc3/create_bitcoin_full_node_with_tor_step_by_step/?st=j5n7z1q1&sh=392084c9

https://hackernoon.com/a-complete-beginners-guide-to-installing-a-bitcoin-full-node-on-linux-2018-edition-cb8e384479ea