How to Run Bitcoin as a Tor Hidden Service on Ubuntu

Why should you run a Bitcoin hidden service on your node?
* It increases the privacy of other Bitcoin users who are anonymizing their actions via Tor. Specifically, it is a countermeasure to many of the “network observer” attacks listed on the Open Bitcoin Privacy Project’s threat model.
* It makes your own node more robust against Sybil attacks and network partitions.
* It doesn’t require much more computational resources to run, just the one-time setup cost of configuring your machine.

There are several ways that you can configure a Bitcoin node to connect to Tor that are outlined in the documentation; for the purpose of this guide we are focused on the third option: “automatically listen on Tor.”

As of Bitcoin Core 0.12, a node will automatically run a hidden service if it is able to connect to a local Tor daemon. However, we have to make sure that a few things are configured correctly so that the node and daemon can talk to each other.

First we need to follow the instructions to install Tor. We’ll need to know the codename of the Ubuntu release:

username@host:~$ lsb_release -c
Codename: xenial

Now we can install Tor; replace <codename> with your version.

username@host:~$ sudo vim /etc/apt/sources.list

Add these two lines to the file and save it:
deb http://deb.torproject.org/torproject.org <codename> main
deb-src http://deb.torproject.org/torproject.org <codename> main

username@host:~$ gpg --keyserver keys.gnupg.net --recv 886DDD89
username@host:~$ gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
username@host:~$ sudo apt-get update
username@host:~$ sudo apt-get install tor deb.torproject.org-keyring

Now that Tor is installed and running, check the configuration:

username@host:~$ sudo vim /usr/share/tor/tor-service-defaults-torrc

Ensure that the following lines are (anywhere) in this config file:

ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

If any of those lines were missing, save the config file and restart the Tor daemon via:

username@host:~$ sudo /etc/init.d/tor restart

Now we need to make sure that the linux user that runs the bitcoind process has access to read the tor authentication cookie. You can determine the name of the Tor user via:

username@host:~$ grep User /usr/share/tor/tor-service-defaults-torrc
User debian-tor

Now modify the user that runs bitcoind on your machine to be a member of the Tor group:

username@host:~$ sudo usermod -a -G debian-tor <username>

At this point (just to be safe) you should open a new terminal window / SSH session to ensure that the bitcoind user has the correct permissions. In the new window, you can check the permissions via:

username@host:~$ id <username>
uid=1000(username) gid=100(users) groups=100(users),121(debian-tor)

If your user is in the tor group, now we can start bitcoind. Make sure to stop it first if it’s currently running.

username@host:~$ bitcoin-cli stop
username@host:~$ bitcoind -daemon -debug=tor

Now check the bitcoin log to make sure the configuration works:

username@host:~$ tail -f ~/.bitcoin/debug.log | grep tor

You should see output like so:

2016–08–18 20:36:10 torcontrol thread start
2016–08–18 20:36:10 tor: Successfully connected!
2016–08–18 20:36:10 tor: Connected to Tor version 0.2.8.6
2016–08–18 20:36:10 tor: Supported authentication method: COOKIE
2016–08–18 20:36:10 tor: Supported authentication method: SAFECOOKIE
2016–08–18 20:36:10 tor: Using SAFECOOKIE authentication, reading cookie authentication from /var/run/tor/control.authcookie
2016–08–18 20:36:10 tor: SAFECOOKIE authentication challenge successful
2016–08–18 20:36:10 tor: AUTHCHALLENGE ServerHash af7da689d08a67d5b4e789a98c76a6eacbabaa32baefc223ab0d7b1f46c3d
2016–08–18 20:36:10 tor: Authentication successful
2016–08–18 20:36:10 tor: ADD_ONION successful
2016–08–18 20:36:10 tor: Got service ID w4bh4cputinlptzm, advertising service w4bh4cputinlptzm.onion:8333
2016–08–18 20:36:10 tor: Cached service private key to /home/username/.bitcoin/onion_private_key
2016–08–18 20:36:10 AddLocal(w4bh4cputinlptzm.onion:8333,4)

If you see this error:

2016-08-18 19:51:48 tor: Add onion failed with unrecognized command (You probably need to upgrade Tor)

Then you didn’t configure Tor’s deb repository correctly and accidentally installed tor from Ubuntu’s out-of-date repository. You’ll need to “sudo apt-get remove tor” and reconfigure the repository before reinstalling it.

If you see this error:

2016–08–18 20:01:28 tor: Error connecting to Tor control socket
2016–08–18 20:01:28 tor: Not connected to Tor control port 127.0.0.1:9051, trying to reconnect

Then your tor-service-defaults-torrc file is misconfigured or you forgot to restart the daemon to make the changes take effect.

If you see this error:

2016–08–18 20:11:10 tor: Authentication cookie /var/run/tor/control.authcookie could not be opened (check permissions)

Then you did not correctly add the linux user that runs bitcoind to the tor group. Also, make sure you log out and back in to ensure that your current shell session has the appropriate groups set!

Otherwise, if everything looks good, visit https://bitnodes.io/ and use the “check node” tool to make sure that it’s accepting connections.

If bitnodes is able to connect, you can optionally click on the green link that appears for your node’s status, scroll to the bottom of your node’s status page, and input your email address to receive alerts if bitnodes ever has issues connecting to your node’s hidden service.

Thank you for running a Bitcoin hidden service!