Skip to content

Commit 11d3b58

Browse files
author
MarcoFalke
committed
Merge #20757: doc: tor.md and -onlynet help updates
193f9a9 doc: update tor.md manual config, move after automatic config (Jon Atack) 9af99b6 doc: update/improve automatic tor section of tor.md (Jon Atack) dfc4ce1 doc: update -proxy, -onion and -onlynet info in tor.md (saibato) 784a278 doc: update -onlynet help in src/init.cpp (Jon Atack) Pull request description: This continues the tor documentation and help improvements of #19961 and clarifies issues that contributors have been mentioning and noticing, like in bitcoin/bitcoin#20555 (comment). More info: - bitcoin/bitcoin#19961 (comment) - bitcoin/bitcoin#19961 (comment) ACKs for top commit: Rspigler: ACK 193f9a9 prayank23: ACK bitcoin/bitcoin@193f9a9 bitcoin/bitcoin@9af99b6 bitcoin/bitcoin@dfc4ce1 Tree-SHA512: edb1b776c4624e1c2e30d829511c226a6492b719f5d1aaaeee1eaade47c108a99c09004d13a05f70b2d65f36db3db647902b5ea36807a87065f34acade33ccea
2 parents e130ff3 + 193f9a9 commit 11d3b58

File tree

2 files changed

+110
-46
lines changed

2 files changed

+110
-46
lines changed

‎doc/tor.md

Lines changed: 109 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,19 @@ outgoing connections, but more is possible.
2323

2424
-proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy
2525
server will be used to try to reach .onion addresses as well.
26+
You need to use -noonion or -onion=0 to explicitly disable
27+
outbound access to onion services.
2628

2729
-onion=ip:port Set the proxy server to use for Tor onion services. You do not
28-
need to set this if it's the same as -proxy. You can use -noonion
30+
need to set this if it's the same as -proxy. You can use -onion=0
2931
to explicitly disable access to onion services.
32+
Note: Only the -proxy option sets the proxy for DNS requests;
33+
with -onion they will not route over Tor, so use -proxy if you
34+
have privacy concerns.
3035

3136
-listen When using -proxy, listening is disabled by default. If you want
32-
to run an onion service (see next section), you'll need to enable
33-
it explicitly.
37+
to manually configure an onion service (see section 3), you'll
38+
need to enable it explicitly.
3439

3540
-connect=X When behind a Tor proxy, you can specify .onion addresses instead
3641
-addnode=X of IP addresses or hostnames in these parameters. It requires
@@ -40,19 +45,112 @@ outgoing connections, but more is possible.
4045
-onlynet=onion Make outgoing connections only to .onion addresses. Incoming
4146
connections are not affected by this option. This option can be
4247
specified multiple times to allow multiple network types, e.g.
43-
ipv4, ipv6, or onion.
48+
ipv4, ipv6 or onion. If you use this option with values other
49+
than onion you *cannot* disable onion connections; outgoing onion
50+
connections will be enabled when you use -proxy or -onion. Use
51+
-noonion or -onion=0 if you want to be sure there are no outbound
52+
onion connections over the default proxy or your defined -proxy.
4453

4554
In a typical situation, this suffices to run behind a Tor proxy:
4655

4756
./bitcoind -proxy=127.0.0.1:9050
4857

58+
## 2. Automatically create a Bitcoin Core onion service
4959

50-
## 2. Manually create a Bitcoin Core onion service
60+
Bitcoin Core makes use of Tor's control socket API to create and destroy
61+
ephemeral onion services programmatically. This means that if Tor is running and
62+
proper authentication has been configured, Bitcoin Core automatically creates an
63+
onion service to listen on. The goal is to increase the number of available
64+
onion nodes.
5165

52-
If you configure your Tor system accordingly, it is possible to make your node also
53-
reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent
54-
config file): *Needed for Tor version 0.2.7.0 and older versions of Tor only. For newer
55-
versions of Tor see [Section 3](#3-automatically-listen-on-tor).*
66+
This feature is enabled by default if Bitcoin Core is listening (`-listen`) and
67+
it requires a Tor connection to work. It can be explicitly disabled with
68+
`-listenonion=0`. If it is not disabled, it can be configured using the
69+
`-torcontrol` and `-torpassword` settings.
70+
71+
To see verbose Tor information in the bitcoind debug log, pass `-debug=tor`.
72+
73+
### Control Port
74+
75+
You may need to set up the Tor Control Port. On Linux distributions there may be
76+
some or all of the following settings in `/etc/tor/torrc`, generally commented
77+
out by default (if not, add them):
78+
79+
```
80+
ControlPort 9051
81+
CookieAuthentication 1
82+
CookieAuthFileGroupReadable 1
83+
```
84+
85+
Add or uncomment those, save, and restart Tor (usually `systemctl restart tor`
86+
or `sudo systemctl restart tor` on most systemd-based systems, including recent
87+
Debian and Ubuntu, or just restart the computer).
88+
89+
On some systems (such as Arch Linux), you may also need to add the following
90+
line:
91+
92+
```
93+
DataDirectoryGroupReadable 1
94+
```
95+
96+
### Authentication
97+
98+
Connecting to Tor's control socket API requires one of two authentication
99+
methods to be configured: cookie authentication or bitcoind's `-torpassword`
100+
configuration option.
101+
102+
#### Cookie authentication
103+
104+
For cookie authentication, the user running bitcoind must have read access to
105+
the `CookieAuthFile` specified in the Tor configuration. In some cases this is
106+
preconfigured and the creation of an onion service is automatic. Don't forget to
107+
use the `-debug=tor` bitcoind configuration option to enable Tor debug logging.
108+
109+
If a permissions problem is seen in the debug log, e.g. `tor: Authentication
110+
cookie /run/tor/control.authcookie could not be opened (check permissions)`, it
111+
can be resolved by adding both the user running Tor and the user running
112+
bitcoind to the same Tor group and setting permissions appropriately.
113+
114+
On Debian-derived systems, the Tor group will likely be `debian-tor` and one way
115+
to verify could be to list the groups and grep for a "tor" group name:
116+
117+
```
118+
getent group | cut -d: -f1 | grep -i tor
119+
```
120+
121+
You can also check the group of the cookie file. On most Linux systems, the Tor
122+
auth cookie will usually be `/run/tor/control.authcookie`:
123+
124+
```
125+
stat -c '%G' /run/tor/control.authcookie
126+
```
127+
128+
Once you have determined the `${TORGROUP}` and selected the `${USER}` that will
129+
run bitcoind, run this as root:
130+
131+
```
132+
usermod -a -G ${TORGROUP} ${USER}
133+
```
134+
135+
Then restart the computer (or log out) and log in as the `${USER}` that will run
136+
bitcoind.
137+
138+
#### `torpassword` authentication
139+
140+
For the `-torpassword=password` option, the password is the clear text form that
141+
was used when generating the hashed password for the `HashedControlPassword`
142+
option in the Tor configuration file.
143+
144+
The hashed password can be obtained with the command `tor --hash-password
145+
password` (refer to the [Tor Dev
146+
Manual](https://2019.www.torproject.org/docs/tor-manual.html.en) for more
147+
details).
148+
149+
150+
## 3. Manually create a Bitcoin Core onion service
151+
152+
You can also manually configure your node to be reachable from the Tor network.
153+
Add these lines to your `/etc/tor/torrc` (or equivalent config file):
56154

57155
HiddenServiceDir /var/lib/tor/bitcoin-service/
58156
HiddenServicePort 8333 127.0.0.1:8334
@@ -106,44 +204,10 @@ for normal IPv4/IPv6 communication, use:
106204

107205
./bitcoind -onion=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -discover
108206

109-
## 3. Automatically create a Bitcoin Core onion service
110-
111-
Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket
112-
API, to create and destroy 'ephemeral' onion services programmatically.
113-
Bitcoin Core has been updated to make use of this.
114-
115-
This means that if Tor is running (and proper authentication has been configured),
116-
Bitcoin Core automatically creates an onion service to listen on. This will positively
117-
affect the number of available .onion nodes.
118-
119-
This new feature is enabled by default if Bitcoin Core is listening (`-listen`), and
120-
requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0`
121-
and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings.
122-
To show verbose debugging information, pass `-debug=tor`.
123-
124-
Connecting to Tor's control socket API requires one of two authentication methods to be
125-
configured. It also requires the control socket to be enabled, e.g. put `ControlPort 9051`
126-
in `torrc` config file. For cookie authentication the user running bitcoind must have read
127-
access to the `CookieAuthFile` specified in Tor configuration. In some cases this is
128-
preconfigured and the creation of an onion service is automatic. If permission problems
129-
are seen with `-debug=tor` they can be resolved by adding both the user running Tor and
130-
the user running bitcoind to the same group and setting permissions appropriately. On
131-
Debian-based systems the user running bitcoind can be added to the debian-tor group,
132-
which has the appropriate permissions. Before starting bitcoind you will need to re-login
133-
to allow debian-tor group to be applied. Otherwise you will see the following notice: "tor:
134-
Authentication cookie /run/tor/control.authcookie could not be opened (check permissions)"
135-
on debug.log.
136-
137-
An alternative authentication method is the use
138-
of the `-torpassword=password` option. The `password` is the clear text form that
139-
was used when generating the hashed password for the `HashedControlPassword` option
140-
in the tor configuration file. The hashed password can be obtained with the command
141-
`tor --hash-password password` (read the tor manual for more details).
142-
143207
## 4. Privacy recommendations
144208

145-
- Do not add anything but Bitcoin Core ports to the onion service created in section 2.
209+
- Do not add anything but Bitcoin Core ports to the onion service created in section 3.
146210
If you run a web service too, create a new onion service for that.
147211
Otherwise it is trivial to link them, which may reduce privacy. Onion
148-
services created automatically (as in section 3) always have only one port
212+
services created automatically (as in section 2) always have only one port
149213
open.

‎src/init.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -448,7 +448,7 @@ void SetupServerArgs(NodeContext& node)
448448
argsman.AddArg("-maxtimeadjustment", strprintf("Maximum allowed median peer time offset adjustment. Local perspective of time may be influenced by peers forward or backward by this amount. (default: %u seconds)", DEFAULT_MAX_TIME_ADJUSTMENT), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
449449
argsman.AddArg("-maxuploadtarget=<n>", strprintf("Tries to keep outbound traffic under the given target (in MiB per 24h). Limit does not apply to peers with 'download' permission. 0 = no limit (default: %d)", DEFAULT_MAX_UPLOAD_TARGET), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
450450
argsman.AddArg("-onion=<ip:port>", "Use separate SOCKS5 proxy to reach peers via Tor onion services, set -noonion to disable (default: -proxy)", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
451-
argsman.AddArg("-onlynet=<net>", "Make outgoing connections only through network <net> (ipv4, ipv6 or onion). Incoming connections are not affected by this option. This option can be specified multiple times to allow multiple networks.", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
451+
argsman.AddArg("-onlynet=<net>", "Make outgoing connections only through network <net> (ipv4, ipv6 or onion). Incoming connections are not affected by this option. This option can be specified multiple times to allow multiple networks. Warning: if it is used with ipv4 or ipv6 but not onion and the -onion or -proxy option is set, then outbound onion connections will still be made; use -noonion or -onion=0 to disable outbound onion connections in this case.", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
452452
argsman.AddArg("-peerbloomfilters", strprintf("Support filtering of blocks and transaction with bloom filters (default: %u)", DEFAULT_PEERBLOOMFILTERS), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
453453
argsman.AddArg("-peerblockfilters", strprintf("Serve compact block filters to peers per BIP 157 (default: %u)", DEFAULT_PEERBLOCKFILTERS), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
454454
argsman.AddArg("-permitbaremultisig", strprintf("Relay non-P2SH multisig (default: %u)", DEFAULT_PERMIT_BAREMULTISIG), ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);

0 commit comments

Comments
 (0)