Tor Support

Configure Bitcoin Core to run as a Tor onion service for enhanced privacy and anonymity

Overview

Bitcoin Core can run as a Tor onion service and connect to other onion services, providing enhanced privacy and resistance to network surveillance. Tor routes your traffic through multiple relays, making it difficult to trace your connection origin.

Starting with Bitcoin Core 22.0, only Tor v3 addresses are supported. Tor v2 addresses are ignored and neither relayed nor stored.

Quick Start

1. Install Tor

   Install Tor on your system:

   # Debian/Ubuntu
   sudo apt install tor
   
   # macOS
   brew install tor
   
2. Start Tor Service

   sudo systemctl start tor
   sudo systemctl enable tor
   
3. Run Bitcoin Core Behind Tor

   bitcoind -proxy=127.0.0.1:9050
   

This configuration anonymizes all outbound Bitcoin connections through the Tor network.

Compatibility

• Bitcoin Core 22.0+: Tor v3 only
• Tor 0.4.6+: v2 support removed
• Recommended Tor version: 0.4.6 or later

Tor v2 addresses are no longer supported. Ensure you’re using Tor v3 addresses ending in .onion (56 characters).

Configuration Methods

There are three main ways to configure Tor with Bitcoin Core:

1. Run Behind a Tor Proxy

The simplest method - route all connections through Tor:

bitcoind -proxy=127.0.0.1:9050

Configuration options:

# Generic proxy (used for all networks including .onion)
-proxy=ip[:port]

# Tor-specific proxy
-proxy=ip[:port]=tor
# or
-onion=ip[:port]

# Explicitly disable onion access
-onion=0
# or
-noonion

The Tor Browser Bundle uses port 9150 by default, while system Tor installations typically use port 9050.

UNIX Domain Sockets

You can use UNIX domain sockets for proxy connections:

bitcoind -onion=unix:/home/user/torsocket

2. Automatic Onion Service

Bitcoin Core can automatically create ephemeral onion services using Tor’s control socket API.

1. Configure Tor Control Port

   Edit /etc/tor/torrc and add/uncomment:

   ControlPort 9051
   CookieAuthentication 1
   CookieAuthFileGroupReadable 1
   DataDirectoryGroupReadable 1
   
2. Restart Tor

   sudo systemctl restart tor
   
3. Configure Permissions (if needed)

   If you see authentication errors:

   # Find Tor group
   getent group | cut -d: -f1 | grep -i tor
   
   # Add user to Tor group
   sudo usermod -a -G debian-tor $USER
   
   # Restart computer or log out/in
   
4. Enable in Bitcoin Core

   bitcoind -proxy=127.0.0.1:9050 -listen -debug=tor
   

Configuration options:

# Enable/disable onion service creation
-listenonion=1  # default when -listen is set
-listenonion=0  # disable

# Tor control settings
-torcontrol=127.0.0.1:9051
-torpassword=yourpassword

Authentication Methods

Cookie Authentication (recommended):

Automatic if the user running bitcoind has read access to Tor’s cookie file (/run/tor/control.authcookie).

Password Authentication:

# Generate hashed password
tor --hash-password mypassword

# Add to /etc/tor/torrc
HashedControlPassword 16:872860B76453A77C...

# Use in Bitcoin Core
bitcoind -torpassword=mypassword

3. Manual Onion Service

Create a persistent onion service manually:

1. Configure Tor

   Add to /etc/tor/torrc:

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

   Virtual port (8333) should match Bitcoin’s P2P port. Target address (127.0.0.1:8334) is where Tor forwards connections.

2. Restart Tor

   sudo systemctl restart tor
   
3. Get Your Onion Address

   sudo cat /var/lib/tor/bitcoin-service/hostname
   

   Example output: 7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion

4. Run Bitcoin Core

   bitcoind -proxy=127.0.0.1:9050 \
     -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion \
     -listen
   

Advanced Configuration

Tor-Only Mode

Connect exclusively to Tor peers:

bitcoind -onlynet=onion -proxy=127.0.0.1:9050

Using -onlynet=onion may make your node more susceptible to Sybil attacks. Consider combining with other networks for better security.

Dual-Stack Configuration

Run reachable from both Tor and clearnet:

# Allow discovery of clearnet addresses
bitcoind -proxy=127.0.0.1:9050 \
  -externalip=your.onion.address \
  -discover

Dual-stack nodes help strengthen the Bitcoin network but may allow traffic analysis to correlate your clearnet and Tor identities.

Tor for Onion Access Only

Use Tor only for .onion addresses, clearnet for others:

bitcoind -onion=127.0.0.1:9050 \
  -externalip=your.onion.address \
  -discover

Bind to Specific Interface

Prevent clearnet connections to your onion-only node:

bitcoind -proxy=127.0.0.1:9050 \
  -bind=127.0.0.1:8334=onion \
  -externalip=your.onion.address \
  -listen

Multiple External IPs

Advertise multiple addresses:

bitcoind -externalip=203.0.113.5 \
  -externalip=your.onion.address

Bitcoin Core will advertise the most compatible address to each peer using heuristics.

Monitoring and Verification

Check Your Onion Address

# CLI netinfo
bitcoin-cli -netinfo

# RPC call
bitcoin-cli getnetworkinfo | grep onion

# Debug log
grep "AddLocal" ~/.bitcoin/debug.log | grep ".onion"

View Onion Peers

# Count of known onion addresses
bitcoin-cli -addrinfo

# Get specific onion peers
bitcoin-cli getnodeaddresses 10 "onion"

# Detailed peer info
bitcoin-cli getpeerinfo | grep -A 10 "onion"

Enable Tor Debug Logging

bitcoind -debug=tor

Check ~/.bitcoin/debug.log for Tor-related messages:

tail -f ~/.bitcoin/debug.log | grep "tor:"

Troubleshooting

Authentication Cookie Error

tor: Authentication cookie could not be opened (check permissions)

Solution:

# Find Tor group
TORGROUP=$(stat -c '%G' /run/tor/control.authcookie)

# Add user to group
sudo usermod -a -G ${TORGROUP} ${USER}

# Restart or log out/in

Connection Issues

# Verify Tor is running
systemctl status tor

# Test Tor connectivity
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org

# Check Bitcoin Core logs
bitcoin-cli -netinfo

Port Conflicts

If using Tor Browser Bundle, it may use port 9150 instead of 9050:

bitcoind -proxy=127.0.0.1:9150

Privacy Recommendations

Best Practices:

1. Dedicated onion service: Don’t add other services to the same onion address
2. Single network: Use -onlynet=onion for maximum privacy
3. No dual-stack: Avoid running on multiple networks if unlinkability is required
4. Block-relay connections: Consider using block-relay-only connections for additional privacy
5. Regular monitoring: Check connections regularly with -netinfo

Operating bridge nodes (listening on both Tor and clearnet) can be correlated through timing analysis and shared runtime characteristics. Only use bridge mode if you don’t require strict identity separation.

Configuration Examples

Maximum Privacy

bitcoin.conf

# Tor-only mode
proxy=127.0.0.1:9050
onlynet=onion
listen=1
listenonion=1
debug=tor

Bridge Node

bitcoin.conf

# Accessible via both Tor and clearnet
proxy=127.0.0.1:9050
externalip=your.onion.address
listen=1
discover=1

Automatic Ephemeral Service

bitcoin.conf

proxy=127.0.0.1:9050
listen=1
listenonion=1
torcontrol=127.0.0.1:9051
debug=tor

Performance Considerations

Tor connections are generally slower than clearnet due to routing through multiple relays:

• Latency: 3-10x higher than direct connections
• Bandwidth: Limited by slowest relay in circuit
• Initial sync: Significantly slower, consider using clearnet initially

For faster initial blockchain download, sync over clearnet first, then switch to Tor-only mode.

See Also

• P2P Network - General network configuration
• I2P Support - Alternative privacy network
• CJDNS Support - Encrypted IPv6 network
• Tor Project Documentation