Introduction #
Bitcoin Core originated from the first Bitcoin software client released by Satoshi Nakamoto, the pseudonymous creator(s) of Bitcoin, in 2009. It was initially called “Bitcoin” but later renamed “Bitcoin Core” to differentiate it from the broader Bitcoin network and currency.
By running Bitcoin Core, participants contribute to the decentralized and consensus-driven nature of the Bitcoin network. Each full node independently validates transactions and blocks, ensuring adherence to the network’s rules without reliance on a central authority.
System User #
Create the user “satoshi” during the initial Ubuntu install. If a different user were created, you could create “satoshi” with the following command.
sudo adduser --gecos "" satoshi
Create a strong password for the user, avoiding special characters.
Provide “satoshi” with sudo permission.
sudo usermod -aG sudo satoshi
Login as the new system user.
su - satoshi
Run a system upgrade. Use the sudo password created previously.
sudo apt update && sudo apt upgrade -y
Install required dependencies.
sudo apt install curl gpg unzip apt-transport-https -y
Local IP #
Throughout the guide, you will need to know your node’s local IP address to modify the various configuration files as needed.
If you don’t know your node’s local IP, run the following command. Note it for future reference.
hostname -I
Configure Tor #
Create a new sources file for Tor.
sudo nano /etc/apt/sources.list.d/tor.list
Paste the following lines, then save and exit the file with “control+x,” confirm with “y,” then “enter.”
deb [signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org jammy main
deb-src [signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org jammy main
Import the Tor project’s gpg key.
sudo wget -qO- https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --dearmor | sudo tee /usr/share/keyrings/tor-archive-keyring.gpg >/dev/null
Install Tor and Tor Debian keyring.
sudo apt update && sudo apt install tor deb.torproject.org-keyring -y
Open the “torrc” file.
sudo nano /etc/tor/torrc
Paste the following at the top of the file, then save and exit.
# Hidden Service Bitcoind
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
Add “satoshi” to the Tor group.
sudo usermod -aG debian-tor satoshi
Configure Bitcoin Daemon #
Download & Verify Core #
Create a downloads directory.
mkdir ~/downloads
Enter the directory.
cd ~/downloads
Visit bitcoincore.org and locate the page for the most current Bitcoin version, avoiding releases marked “test.” At the time of writing, v27.0 is the most recent release.
Copy the URL for the latest “x86_64-linux-gnu.tar.gz” package and download using “wget.”
torsocks wget https://bitcoincore.org/bin/bitcoin-core-27.0/bitcoin-27.0-x86_64-linux-gnu.tar.gz
On the same page, download the “SHA256SUMS” file.
torsocks wget https://bitcoincore.org/bin/bitcoin-core-27.0/SHA256SUMS
Then download “SHA256SUMS.asc”.
torsocks wget https://bitcoincore.org/bin/bitcoin-core-27.0/SHA256SUMS.asc
Verify the checksum of the download.
sha256sum --ignore-missing --check SHA256SUMS
The output should show an “ok” message, for example: “bitcoin-0.0-x86_64-linux-gnu.tar.gz: OK.”
Verify the release’s validity by checking the signatures against the known developer keys from the official Core repository.
Import developer keys to GPG keyring.
torsocks curl -s https://api.github.com/repos/bitcoin-core/guix.sigs/contents/builder-keys | \
grep download_url | cut -d '"' -f 4 | \
xargs -n 1 curl -O && \
ls *.gpg | xargs -n 1 gpg --import && \
rm *.gpg
Verify the signatures.
gpg --verify SHA256SUMS.asc
This will output a series of signature checks for each public key that signed the checksums.
The keys previously imported into your keyring should show a “gpg: Good signature” message.
Don’t worry about “This key is not certified with a trusted signature!” warnings. Enhanced trust levels have not been manually set for the imported keys.
Remove the downloaded verification files.
rm SHA256SUMS && rm SHA256SUMS.asc
Unpackage Bitcoin Core.
tar xzf bitcoin-*-x86_64-linux-gnu.tar.gz
Remove the archive.
rm -r bitcoin-*-x86_64-linux-gnu.tar.gz
Installing Core #
Run the following command to install Bitcoin Core.
sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-*/bin/*
Remove the leftover folder.
rm -r bitcoin-*/
Restart the Tor daemon.
sudo systemctl restart tor
Start the Bitcoin daemon, then stop it again after a few seconds.
bitcoind -daemon
bitcoin-cli stop
Configuration #
Create a Bitcoin configuration file.
nano ~/.bitcoin/bitcoin.conf
Paste the following lines into the file.
#proxy=127.0.0.1:9050
#listen=1
#bind=127.0.0.1
#onlynet=onion
server=1
txindex=1
daemon=1
pruned=0
dbcache=1024
peerbloomfilters=1
rpcport=8332
rpcbind=0.0.0.0
rpcallowip=127.0.0.1
rpcallowip=10.0.0.0/8
rpcallowip=172.0.0.0/8
rpcallowip=192.0.0.0/8
zmqpubrawblock=tcp://0.0.0.0:28332
zmqpubrawtx=tcp://0.0.0.0:28333
zmqpubhashblock=tcp://0.0.0.0:28334
whitelist=127.0.0.1
You must now choose whether to synchronize the blockchain via clearnet or Tor. If synchronizing as quickly as possible is a priority, leave the hashes on the top 4 lines in place. Note that remaining patient with a Tor sync is hugely encouraged.
Using a VPN set at the router level is highly recommended if using clearnet.
If synchronizing anonymously is your priority, remove the hashes from these 4 lines to ensure bitcoind never connects via clearnet with a permanent Tor connection. This takes much longer than a clearnet sync; however, the privacy benefits are substantial.
You also have the option of enabling or disabling “Mempool Full-RBF.” If you want to ensure your choice persists throughout Core updates, regardless of what defaults future releases settle on, It’s recommended to flag this in your conf file using either the enable (1) or disable (0) argument.
You can ignore this line if you are happy to flow with any defaults chosen for you in future updates.
mempoolfullrbf=0
Leave the file open and start a new terminal session. SSH in and download the raw “rpcauth.py file” from the Bitcoin repository.
torsocks wget https://raw.githubusercontent.com/bitcoin/bitcoin/27.x/share/rpcauth/rpcauth.py
Set the correct file permissions.
chmod +x rpcauth.py
Run the following command, replacing “PASSWORDHERE” with a strong RPC password for Bitcoin Core. Avoid using special characters.
./rpcauth.py bitcoin PASSWORDHERE
Copy the RPC string, starting “rpcauth=bitcoin,” and paste it, including the long string of numbers that follow, to the bottom of the “bitcoin.conf” file, open in your first terminal window.
Save and exit the file.
Remove the “rpcauth.py” file.
rm rpcauth.py
Service File #
Create a service file to start Bitcoin automatically on system boot.
cd /etc/systemd/system/
Copy the link to the raw “bitcoind.service” file from the Bitcoin repo and download.
sudo torsocks wget https://raw.githubusercontent.com/bitcoin/bitcoin/27.x/contrib/init/bitcoind.service
Open the downloaded file.
sudo nano bitcoind.service
Make the following edits.
####change
ExecStart=/usr/bin/bitcoind -pid=/run/bitcoind/bitcoind.pid \
-conf=/etc/bitcoin/bitcoin.conf \
-datadir=/var/lib/bitcoind \
-startupnotify='systemd-notify --ready' \
-shutdownnotify='systemd-notify --stopping'
##to
ExecStart=/usr/local/bin/bitcoind -pid=/run/bitcoind/bitcoind.pid \
-conf=/home/satoshi/.bitcoin/bitcoin.conf \
-datadir=/home/satoshi/.bitcoin \
-startupnotify='systemd-notify --ready' \
-shutdownnotify='systemd-notify --stopping'
####comment out
ExecStartPre=/bin/chgrp bitcoin /etc/bitcoin
##like this
#ExecStartPre=/bin/chgrp bitcoin /etc/bitcoin
####edit
User=bitcoin
Group=bitcoin
##to
User=satoshi
Group=satoshi
####comment out
ProtectHome=true
##like this
#ProtectHome=true
Save the file & exit.
Enable the service file.
sudo systemctl enable bitcoind
If synchronizing over Tor, continue immediately to the Tor Peers step.
Clearnet Sync #
(Skip if synchronizing via Tor)
If synchronizing over clearnet, wait for the initial block download to complete before continuing to the Tor peers step.
Start bitcoind
sudo systemctl start bitcoind
Monitor progress by running the following command from the home directory. Once logs show “progress=1.000000,” IBD is complete.
tail -f .bitcoin/debug.log
Next, remove the hashes from the proxy, listen, bind, and onlynet lines within the conf file, then restart bitcoind before continuing. This ensures that all future block data is only downloaded via Tor.
sudo systemctl stop bitcoind
nano ~/.bitcoin/bitcoin.conf
sudo systemctl restart bitcoind
Continue to the Tor Peers step.
Tor Peers #
The first Tor peer needs to be added manually. Open “bitcoin.conf,” then visit the Tor node page at Bitnodes.io in a web browser.
nano ~/.bitcoin/bitcoin.conf
Select an active node from the list and copy the Tor address and port number.
Return to the terminal and paste the address at the bottom of the “bitcoin.conf” file.
As shown in the example below, include the “addnode=” prefix.
addnode=ufi6x4yympldoxmzgszvq5pb3pzixxjicvrhssrmky23f5bgxfxlfqd.onion:8333
Warning: This example is not an active node and should not be used.
Save and exit the file, then reboot the node.
sudo reboot
Wait a few minutes, then SSH into the node as “satoshi.”
Check that the node is successfully connecting to Tor peers. Depending on your waiting time, you may need to run this command several times.
bitcoin-cli getconnectioncount
If the output shows several peers, you can return to “bitcoin.conf” and remove the entire “addnode” line, then save and exit.
nano .bitcoin/bitcoin.conf
Restart Bitcoin CLI.
sudo systemctl restart bitcoind
Wait a few minutes, then check that you are still connecting to Tor nodes.
bitcoin-cli getconnectioncount
Networking #
Confirm that network traffic only passes through Tor.
The output should show a “reachable false” status for both “IPV4” and “IPV6”.
Also, confirm that “onion” shows a “reachable true” status.
bitcoin-cli getnetworkinfo
The output also displays your Bitcoin Core onion address. This is useful for services requiring a direct connection to Core.
You can also make direct requests for your Bitcoin onion address.
bitcoin-cli getnetworkinfo | grep address.*onion
Those synchronizing over Tor can now monitor progress by running the following command from the home directory.
tail -f .bitcoin/debug.log
Wait until Core sync is finished before continuing. Once logs show “progress=1.000000,” IBD is complete.