Changeset View
Changeset View
Standalone View
Standalone View
doc/tor.md
# TOR SUPPORT IN BITCOIN | # TOR SUPPORT IN BITCOIN | ||||
It is possible to run Bitcoin ABC as a Tor hidden service, and connect to such services. | It is possible to run Bitcoin ABC as a Tor onion service, and connect to such services. | ||||
The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly | The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly | ||||
configure Tor. | configure Tor. | ||||
## 1. Run Bitcoin ABC behind a Tor proxy | ## 1. Run Bitcoin ABC behind a Tor proxy | ||||
The first step is running Bitcoin ABC behind a Tor proxy. This will already anonymize all | The first step is running Bitcoin ABC behind a Tor proxy. This will already anonymize all | ||||
outgoing connections, but more is possible. | outgoing connections, but more is possible. | ||||
-proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy | -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy | ||||
server will be used to try to reach .onion addresses as well. | server will be used to try to reach .onion addresses as well. | ||||
-onion=ip:port Set the proxy server to use for Tor hidden services. You do not | -onion=ip:port Set the proxy server to use for Tor onion services. You do not | ||||
need to set this if it's the same as -proxy. You can use -noonion | need to set this if it's the same as -proxy. You can use -noonion | ||||
to explicitly disable access to hidden services. | to explicitly disable access to onion services. | ||||
-listen When using -proxy, listening is disabled by default. If you want | -listen When using -proxy, listening is disabled by default. If you want | ||||
to run a hidden service (see next section), you'll need to enable | to run an onion service (see next section), you'll need to enable | ||||
it explicitly. | it explicitly. | ||||
-connect=X When behind a Tor proxy, you can specify .onion addresses instead | -connect=X When behind a Tor proxy, you can specify .onion addresses instead | ||||
-addnode=X of IP addresses or hostnames in these parameters. It requires | -addnode=X of IP addresses or hostnames in these parameters. It requires | ||||
-seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with | -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with | ||||
other P2P nodes. | other P2P nodes. | ||||
-onlynet=onion Make outgoing connections only to .onion addresses. Incoming | -onlynet=onion Make outgoing connections only to .onion addresses. Incoming | ||||
▲ Show 20 Lines • Show All 58 Lines • ▼ Show 20 Lines | |||||
If you only want to use Tor to reach .onion addresses, but not use it as a proxy | If you only want to use Tor to reach .onion addresses, but not use it as a proxy | ||||
for normal IPv4/IPv6 communication, use: | for normal IPv4/IPv6 communication, use: | ||||
./bitcoind -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover | ./bitcoind -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover | ||||
## 3. Automatically listen on Tor | ## 3. Automatically listen on Tor | ||||
Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket | Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket | ||||
API, to create and destroy 'ephemeral' hidden services programmatically. | API, to create and destroy 'ephemeral' onion services programmatically. | ||||
Bitcoin ABC has been updated to make use of this. | Bitcoin ABC has been updated to make use of this. | ||||
This means that if Tor is running (and proper authentication has been configured), | This means that if Tor is running (and proper authentication has been configured), | ||||
Bitcoin ABC automatically creates a hidden service to listen on. This will positively | Bitcoin ABC automatically creates an onion service to listen on. This will positively | ||||
affect the number of available .onion nodes. | affect the number of available .onion nodes. | ||||
This new feature is enabled by default if Bitcoin ABC is listening (`-listen`), and | This new feature is enabled by default if Bitcoin ABC is listening (`-listen`), and | ||||
requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0` | requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0` | ||||
and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings. | and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings. | ||||
To show verbose debugging information, pass `-debug=tor`. | To show verbose debugging information, pass `-debug=tor`. | ||||
Connecting to Tor's control socket API requires one of two authentication methods to be | Connecting to Tor's control socket API requires one of two authentication methods to be | ||||
configured. It also requires the control socket to be enabled, e.g. put `ControlPort 9051` | configured. It also requires the control socket to be enabled, e.g. put `ControlPort 9051` | ||||
in `torrc` config file. For cookie authentication the user running bitcoind must have read | in `torrc` config file. For cookie authentication the user running bitcoind must have read | ||||
access to the `CookieAuthFile` specified in Tor configuration. In some cases this is | access to the `CookieAuthFile` specified in Tor configuration. In some cases this is | ||||
preconfigured and the creation of a hidden service is automatic. If permission problems | preconfigured and the creation of an onion service is automatic. If permission problems | ||||
are seen with `-debug=tor` they can be resolved by adding both the user running Tor and | are seen with `-debug=tor` they can be resolved by adding both the user running Tor and | ||||
the user running bitcoind to the same group and setting permissions appropriately. On | the user running bitcoind to the same group and setting permissions appropriately. On | ||||
Debian-based systems the user running bitcoind can be added to the debian-tor group, | Debian-based systems the user running bitcoind can be added to the debian-tor group, | ||||
which has the appropriate permissions. Before starting bitcoind you will need to re-login | which has the appropriate permissions. Before starting bitcoind you will need to re-login | ||||
to allow debian-tor group to be applied. Otherwise you will see the following notice: "tor: | to allow debian-tor group to be applied. Otherwise you will see the following notice: "tor: | ||||
Authentication cookie /run/tor/control.authcookie could not be opened (check permissions)" | Authentication cookie /run/tor/control.authcookie could not be opened (check permissions)" | ||||
on debug.log. | on debug.log. | ||||
An alternative authentication method is the use | An alternative authentication method is the use | ||||
of the `-torpassword=password` option. The `password` is the clear text form that | of the `-torpassword=password` option. The `password` is the clear text form that | ||||
was used when generating the hashed password for the `HashedControlPassword` option | was used when generating the hashed password for the `HashedControlPassword` option | ||||
in the tor configuration file. The hashed password can be obtained with the command | in the tor configuration file. The hashed password can be obtained with the command | ||||
`tor --hash-password password` (read the tor manual for more details). | `tor --hash-password password` (read the tor manual for more details). | ||||
## 4. Privacy recommendations | ## 4. Privacy recommendations | ||||
- Do not add anything but Bitcoin ABC ports to the hidden service created in section 2. | - Do not add anything but Bitcoin ABC ports to the onion service created in section 2. | ||||
If you run a web service too, create a new hidden service for that. | If you run a web service too, create a new onion service for that. | ||||
Otherwise it is trivial to link them, which may reduce privacy. Hidden | Otherwise it is trivial to link them, which may reduce privacy. Hidden | ||||
services created automatically (as in section 3) always have only one port | services created automatically (as in section 3) always have only one port | ||||
open. | open. |