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

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

11 min readJan 10, 2019

Full Nodes are Bitcoin’s nervous system!

This article updated in February 2021 with latest info and corrections, including VirtualBox 6.1.18, Ubuntu Server 20.04.2LTS, and Bitcoin Core 0.21.0

Have you thought about experimenting with a full bitcoin node but are concerned about privacy or messing up 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 in a virtual machine. You needn’t worry about corrupting your main/host OS, and you’ll have a low-risk Bitcoin node for experimenting. 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.

*** Note — I’m considering writing a companion tutorial for additional items, such as setting up bitcoind to run as a system service automatically on boot, as well as an overview of tools and commands that can be useful to monitor and manage your node. If that sounds useful, please let a comment saying so! ***

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 330GB (as of Feb 2021) 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.18) for your platform, which for me (on Windows 10) is VirtualBox-6.1.18–142142-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 for five years.

This is great for a “headless” (no GUI) server where no graphics or consumer applications are needed. That being said, you could use their newer, more frequently updated version. Just be aware that things might break… 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 20.04.2 LTS) from Ubuntu’s website: https://releases.ubuntu.com/20.04.2/ubuntu-20.04.2-live-server-amd64.iso

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

Once the ISO (disc image) file has downloaded, start Virtual Box. You’ll be presented with the main interface, which is rather empty at the moment. 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 32GB of RAM on my host computer, so I will choose ~8GB 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 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 to confirm each selection)

** Installer Update ***
You may be prompted to update the installer at some 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 checked

UNCHECK Set up this disk as an LVM group selected

Page 6b — Storage configuration

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 — Installing system

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

Page 10a — Installation complete!

Choose Reboot Now 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 proceeding to the next section of this guide, make sure the 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://kifarunix.com/install-virtualbox-guest-additions-on-ubuntu-20-04/#auto-install

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 install build-essential autoconf libtool pkg-config libboost-all-dev libssl-dev libevent-dev doxygen libzmq3-dev libdb++-dev libsqlite3-dev

Finally, we are ready to 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:

git clone https://github.com/bitcoin/bitcoin.git

Before proceeding, we’ll need to install the BerkeleyDB database software that is required for Bitcoin’s wallet functionality. Note that Bitcoin Core is moving away from the ancient BerkeleyDB currently used to a modern SQLite version, but for now BerkeleyDB is still required for backwards compatibility. Fortunately there is a script that will automatically download and compile BDB for you. Enter the commands below, one at at time:

cd bitcoin./contrib/install_db4.sh `pwd`

Note that the pwd above is surrounded by backticks (which are on the tilde key), not single quotes

Now we can proceed with checking out the latest version of Bitcoin Core and compiling. Again, enter the following commands one at a time:

git checkout v0.21.0git 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 and to disable other unneeded libraries:

export BDB_PREFIX="$HOME/bitcoin/db4"./configure BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" BDB_CFLAGS="-I${BDB_PREFIX}/include" --with-gui=no --with-miniupnpc=no

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!

makemake checksudo 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 .bitcointouch .bitcoin/bitcoin.confecho "txindex=1" >> .bitcoin/bitcoin.confecho "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 any of the above lines are missing, add them to the local configuration file using the echo command as before, for example:

sudo sh -c "echo 'ControlPort 9051' >> /etc/tor/torrc"

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

sudo systemctl restart tor

You can check to make sure Tor initialized properly after the changes by running

journalctl -f | grep tor -i

If you don’t see any errors in the above command, Tor should be ready.

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 logout (just type logout and hit Enter) and log back in to make sure group membership is updated (can also just restart the VM if you prefer by typing sudo reboot now).

Part Seven— Bitcoin Lives!!!

Once logged back in, you are finally ready to launch Bitcoin over Tor!

bitcoind -daemon -debug=tor

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 disabled in the output of the following command to ensure you are operating ONLY over Tor:

bitcoin-cli getnetworkinfo

The output should show

"networks": [
  {
    "name": "ipv4",
    "limited": true,
    "reachable": false,... (and the same for the ipv6 entry) ...    "name": "onion",
    "limited": false;
    "reachable": true,
...

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!