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!
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 upgradeEnter 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 universeAdditional 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-devFinally, 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.shA 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.confExperiment 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 torEnsure 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-torrcIf 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 torYou can check to make sure Tor initialized properly after the changes by running
journalctl -f | grep tor -iIf 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 usernameNow 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=torYou can use the following command to monitor progress:
tail -f ~/.bitcoin/debug.logIt 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 getnetworkinfoThe 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!
bitcoin-cli getpeerinfo | grep trueYou can also quickly see a list of onion nodes you are connected to by running:
bitcoin-cli getpeerinfo | grep addrPart Eight—The End
I hope you’ve found this guide useful. Feel free to ask any questions or note any 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
