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 10 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 other platforms such as Windows and macOS. The instructions for Windows are presented at the end.

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 since version 22.0 Bitcoin does not support Tor hidden service version 2 (ie. short onion addresses), only support Tor version 3 hidden services (Tor v3, 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.

Linux 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. 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. Usually it is the same as the currently logged-in user, but in some setups, it may be different. 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

At this point your node will work over Tor without further configuartion. Bitcoin Core v0.12 and later automatically tries to connect to Tor via the ControlPort if listen=1 is set in bitcoin.conf. By default Bitcoin Core will usually connect over the regular Internet as well as allow connections to and from the Tor 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

Note that port 9051 is the ControlPort. This is the port used to control the Tor service. It is not the port Bitcoin Core uses - port 9050 is the SOCKS proxy for tunneling Bitcoin Core's traffic via Tor.

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.

Linux 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.

Windows

First you need to download Tor, we recommend the Tor Expert Bundle (intended for developers who need to bundle tor with their applications), it contains only the tor and pluggable transports binaries, bridge strings, and geoip data. The latest version for Windows 64bits (x86_64) or Windows 32bits (i686) is located here on torproject.org. The Tor Expert Bundle is also available for macOS, Linux, and Android, and setup on these platforms is similar to the Windows instructions.

Then extract the contents on a folder in a place that your user can access, like %UserProfile%.

On your Windows Explorer go to that folder and create a file called torrc. Open it with Notepad, type the content below and save:

ControlPort 9051
CookieAuthentication 1

Open Windows PowerShell (maybe you will need to Open as Administrator), navigate to the extracted folder (ex.: cd C:\Users\MyUserName\torExpertBundle), and enter the folder Tor (ie.: cd Tor). Type dir you should see some files and tor.exe among them. So type the code below (remember to change the folder accordingly to where you extracted)

tor.exe --service install -options -f "C:\Users\MyUserName\torExpertBundle\Tor\torrc"

If the code succeeds it will say something related to the creation of a new entry on Windows Services. Access Windows Services by pressing the Windows button and typing services then enter. You should see Tor Win32 Service (Provides an anonymous Internet communication system) on the list. Check if the status is Running and initialization type is Automatic. To verify if Tor is really working as a service, open Windows PowerShell then type:

netstat -aon | findstr ":9050"

You should see something like :9050 LISTENING:

  TCP    127.0.0.1:9050         0.0.0.0:0              LISTENING       4000

Then type:

netstat -aon | findstr ":9051"

You should see something like :9051 LISTENING:

  TCP    127.0.0.1:9051         0.0.0.0:0              LISTENING       4000

If you don't see any LISTENING output, it means that Tor service is not working properly and this issue may be related to Windows permissions on the folder you extracted. To fix it go to where you extracted the Tor Expert Bundle and check the top folder Properties > Security > Advanced and verify if in the Permissions tab you have SERVICE with Full Control, if not click Add, click on the link Select a Secure Entity and type SERVICE (all letters in UPPERCASE) then hit enter and select Full Control (Try to start the Tor service again in Windows Services, if it doesn't work, try adding SYSTEM and LOCAL SERVICE with Full Control on folder permissions and repeat the tests above).

See BitcoinCore debug.log file what is happening on the communication with the Tor service, edit your bitcoin.conf file and add this line at the end debug=tor, then restart BitcoinCore. If everything is ok, you should see something like that:

2022-06-13T21:45:32Z Config file arg: debug="tor"
2022-06-13T21:45:44Z torcontrol thread start
2022-06-13T21:45:44Z tor: Reading cached private key from C:\YourBitcoinFolder\onion_v3_private_key
2022-06-13T21:45:44Z tor: Successfully connected!
2022-06-13T21:45:44Z tor: Connected to Tor version 0.4.x.x
2022-06-13T21:45:44Z tor: Supported authentication method: COOKIE
2022-06-13T21:45:44Z tor: Supported authentication method: SAFECOOKIE
2022-06-13T21:45:44Z tor: Using SAFECOOKIE authentication, reading cookie authentication from C:\Windows\ServiceProfiles\LocalService\AppData\Roaming\tor\control_auth_cookie
2022-06-13T21:45:44Z Leaving InitialBlockDownload (latching to false)
2022-06-13T21:45:44Z tor: SAFECOOKIE authentication challenge successful
2022-06-13T21:45:44Z tor: AUTHCHALLENGE ServerHash xxxxx ServerNonce xxxxx
2022-06-13T21:45:44Z tor: Authentication successful

If you get tor: Authentication cookie C:\Windows\ServiceProfiles\LocalService\AppData\Roaming\tor\control_auth_cookie could not be opened (check permissions) on Bitcoin debug.log this means that you need to navigate to the folder C:\Windows\ServiceProfiles\LocalService and enter Properties > Security > Advanced to verify if in the Permissions tab you have SERVICE with Full Control, if not click Add, click on the link Select a Secure Entity and type SERVICE (all letters in UPPERCASE) then hit enter and select Full Control (Try to start BitcoinCore again, if it doesn't work, try adding SYSTEM and LOCAL SERVICE with Full Control on folder permissions and repeat the tests above... you may need to add All Application Packages, NETWORK SERVICE, USERS, or other security groups, with at least "Read & execute" in order to work).

Related Resources

• KeepItSimpleBitcoin How To Install Tor (Mac OS, Linux, Windows) - text and video instructions including Bitcoin Core config.
• Bitcoin Core Docs Tor - Explanation of the Bitcoin Core configs related to Tor.