highperfocused/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-04-13 22:59:34 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc: update/improve automatic tor section of tor.md

Browse Source
This commit is contained in:
Jon Atack 2020-10-15 12:24:07 +02:00
parent dfc4ce1273
commit 9af99b6f39
No known key found for this signature in database
GPG Key ID: 4F5721B3D0E3921D
1 changed files with 84 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
doc/tor.md
View File

@ -117,37 +117,94 @@ for normal IPv4/IPv6 communication, use:
## 3. Automatically create a Bitcoin Core onion service
Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket
API, to create and destroy 'ephemeral' onion services programmatically.
Bitcoin Core has been updated to make use of this.
Bitcoin Core makes use of Tor's control socket API to create and destroy
ephemeral onion services programmatically. This means that if Tor is running and
proper authentication has been configured, Bitcoin Core automatically creates an
onion service to listen on. The goal is to increase the number of available
onion nodes.
This means that if Tor is running (and proper authentication has been configured),
Bitcoin Core automatically creates an onion service to listen on. This will positively
affect the number of available .onion nodes.
This feature is enabled by default if Bitcoin Core is listening (`-listen`) and
it requires a Tor connection to work. It can be explicitly disabled with
`-listenonion=0`. If it is not disabled, it can be configured using the
`-torcontrol` and `-torpassword` settings.
This new feature is enabled by default if Bitcoin Core is listening (`-listen`), and
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.
To show verbose debugging information, pass `-debug=tor`.
To see verbose Tor information in the bitcoind debug log, pass `-debug=tor`.
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`
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
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
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,
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:
Authentication cookie /run/tor/control.authcookie could not be opened (check permissions)"
on debug.log.
### Control Port
An alternative authentication method is the use
of the `-torpassword=password` option. The `password` is the clear text form that
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
`tor --hash-password password` (read the tor manual for more details).
You may need to set up the Tor Control Port. On Linux distributions there may be
some or all of the following settings in `/etc/tor/torrc`, generally commented
out by default (if not, add them):
```
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```
Add or uncomment those, save, and restart Tor (usually `systemctl restart tor`
or `sudo systemctl restart tor` on most systemd-based systems, including recent
Debian and Ubuntu, or just restart the computer).
On some systems (such as Arch Linux), you may also need to add the following
line:
```
DataDirectoryGroupReadable 1
```
### Authentication
Connecting to Tor's control socket API requires one of two authentication
methods to be configured: cookie authentication or bitcoind's `-torpassword`
configuration option.
#### Cookie authentication
For cookie authentication, the user running bitcoind must have read access to
the `CookieAuthFile` specified in the Tor configuration. In some cases this is
preconfigured and the creation of an onion service is automatic. Don't forget to
use the `-debug=tor` bitcoind configuration option to enable Tor debug logging.
If a permissions problem is seen in the debug log, e.g. `tor: Authentication
cookie /run/tor/control.authcookie could not be opened (check permissions)`, it
can be resolved by adding both the user running Tor and the user running
bitcoind to the same Tor group and setting permissions appropriately.
On Debian-derived systems, the Tor group will likely be `debian-tor` and one way
to verify could be to list the groups and grep for a "tor" group name:
```
getent group | cut -d: -f1 | grep -i tor
```
You can also check the group of the cookie file. On most Linux systems, the Tor
auth cookie will usually be `/run/tor/control.authcookie`:
```
stat -c '%G' /run/tor/control.authcookie
```
Once you have determined the `${TORGROUP}` and selected the `${USER}` that will
run bitcoind, run this as root:
```
usermod -a -G ${TORGROUP} ${USER}
```
Then restart the computer (or log out) and log in as the `${USER}` that will run
bitcoind.
#### `torpassword` authentication
For the `-torpassword=password` option, the password is the clear text form that
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 `tor --hash-password
password` (refer to the [Tor Dev
Manual](https://2019.www.torproject.org/docs/tor-manual.html.en) for more
details).
## 4. Privacy recommendations