Setting up a Tor hidden service

If you use a Bitcoin full node over Tor, then usually it will only be able to make outgoing connections. Therefore, you will only get a maximum of 8 total connections. This is fine, and is not something you usually need to worry about, but if your computer is often online and you want to be a big help to the network, you can run a Tor hidden service in order to accept incoming connections over Tor.

Note that there is no need to forward port 8333 when using a Tor hidden service. The hidden service will cause most firewalls and NAT setups to be bypassed. For this reason, running a Tor hidden service is also a good idea if you want incoming connections but are for some reason unable to forward port 8333.

Prerequisites

These instructions are for Linux. It is possible to do on Windows, but the instructions would be rather different. (If you've done it on Windows, consider adding the instructions to this page.)

You need Tor (at least version 0.2.7.1). Figure out where your torrc file is (/etc/tor/torrc is one possibility). This guide assumes default Tor settings. This guide assumes that Tor is running under the user and group tor, which will usually be the case if you install Tor using your distro's package manager. Note that Bitcoin does not support hidden service version 3 (ie. long onion addresses).

You need Bitcoin Core (or similar). For method 1, you need at least version 0.12.0. Find bitcoin.conf in your data directory.

Method 1 (recommended)

This sets up an automatic hidden service that is initiated by Bitcoin Core. On the first startup of bitcoind after configuring Bitcoin Core to use Tor ControlPort as follows, Bitcoin Core will generate a file called onion_private_key in the data directory (default: ~/.bitcoin, or specified using -datadir=/path/to/bitcoin/data at the command line or datadir=/path/to/bitcoin/data in bitcoin.conf). The file onion_private_key contains the private key needed to generate your unique XXXXXXX.onion address. KEEP THIS SAFE. If someone copies this file they can run a server with your .onion address. Also, if you delete this file, the next time bitcoind loads it will generate a new key file and xxxxxxxx.onion address. Note that while a malicious party cannot necessarily associate the server with you as a person, as long as your server has the same xxxx.onion address they will know it is run by the same person. For absolute security delete onion_private_key at each reboot or some frequent interval.

Add these lines to your torrc:

ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

You need to figure out what user bitcoind or bitcoin-qt is running as. Run the following command while Bitcoin is running:

ps -eo user,group,comm |egrep 'bitcoind|bitcoin-qt' |awk '{print "Bitcoin user: " $1}'

Write down the reported user.

Run the following command as root, which adds your Bitcoin user to the tor group. Replace BITCOIN_USER with the actual user name found above:

usermod -a -G tor BITCOIN_USER

If you don't modify any other settings, Bitcoin Core will usually connect over the regular Internet, but will also allow connections to and from the hidden service. This will help other users who wish to submit transactions to the bitcoin network securely and obscurely, but transactions you submit could theoretically be traced back to your ip address. If you want Bitcoin Core to only connect via Tor (for anonymity), add these lines to bitcoin.conf:

proxy=127.0.0.1:9050
listen=1
bind=127.0.0.1

If you additionally want Bitcoin Core to only connect out to Tor hidden services, also add this line (not particularly recommended):

onlynet=onion

Doing so will make your specific bitcoind node arguably more secure because it will never have an unencrypted connection to another node, but if everyone used onlynet=onion nobody on the onion bitcoin chain would be able to communicate with the clearnet chain. It is essential that some nodes access both clearnet and Tor. If you need to submit bitcoin transactions to the network with the highest level of obscurity, use onlynet=onion. If you only wish to give access to your node to other Tor users, do not use it.

Now restart Tor, and then Bitcoin Core. At some point during startup in ~/.bitcoin/debug.log you will see

tor: Got service ID XXXXXXXXXXX, advertising service XXXXXXXXXXX.onion:8333

This is the .onion address of your server. You should eventually get incoming connections via the hidden service.

Method 2

This sets up a manual hidden service controlled by the tor daemon. The hidden service address (xxxx.onion). Note that as in method 1, your xxxxx.onion address will stay the same until you delete your key file. Someone tracking you can't necessarily associate the xxxx.onion with you, but they will know it is run by the same person or entity.

Add these lines to your torrc:

HiddenServiceDir /var/lib/tor/bitcoin-service/
HiddenServicePort 8333 127.0.0.1:8333

Restart Tor. As root, run cat /var/lib/tor/bitcoin-service/hostname. Your onion address will be reported. If it didn't work, then probably your distro's version of Tor doesn't actually use /var/lib/tor for this purpose. You should try to figure out the correct HiddenServiceDir location.

In the following steps, replace ONION_ADDR with the onion address reported above.

If you don't care about anonymity and are only looking to help the network, add the following lines to bitcoin.conf:

onion=127.0.0.1:9050
listen=1
externalip=ONION_ADDR
discover=1

This will allow you to accept connections both via your onion address and your IP address (if you have port 8333 forwarded), and Tor will only be used for connections to and from Tor hidden services.

If you care about anonymity, instead of the above, add the following lines to bitcoin.conf to use Tor for everything:

proxy=127.0.0.1:9050
listen=1
bind=127.0.0.1
externalip=ONION_ADDR

If you additionally want Bitcoin Core to only connect out to Tor hidden services, also add this line (not particularly recommended):

onlynet=onion

Now restart Bitcoin Core. You should eventually get incoming connections via your hidden service.