doc: Improve Tor docs #21157

ghost commented at 9:45 PM on February 11, 2021: none

Highlight the part which mentioned about DNS requests and Tor usage
Add an example to make it easier for normal users or even power users to ignore all the other details and try basic setup first to avoid confusion
Add 4 privacy recommendations

About usage of Tor and Tor bridges, suggestions to consider tradeoffs based on user environment.
Mention about Deleting "onion_v3_private_key" frequently doesn't help and for some users its better to not use Bitcoin Core Onion Service.
Trade-offs involved in using onlynet=onion
Downloading packages using torsocks Context: #20757 (review)

Reasons:

Point mentioned about DNS requests is important. I am not sure if we can include more details in this doc but it should be highlighted. I had asked one related question recently on Reddit: https://www.reddit.com/r/Bitcoin/comments/l641hj/dns_requests_in_bitcoin_core/
Usage of Tor and Tor bridges is not same in all places. Users should be aware of such things.
Adding an example makes it easier for normal users to refer this doc when they try Bitcoin Core Onion Service first instead of reading several other articles, thread, questions etc. on different websites. Recently someone tweeted a thread about installing Bitcoin Core: https://twitter.com/Ethan_Heilman/status/1355645616056098817

Fixes #19923

in doc/tor.md:180 in 0a02968f1c outdated

 175 | +- Details of `bitcoin.conf` file:
 176 | +
 177 | +  ```
 178 | +  listen=1
 179 | +  torcontrol=127.0.0.1:9051
 180 | +  onlynet=onion

jonatack commented at 9:52 PM on February 11, 2021:

ISTM that onlynet=onion is not a particularly recommended option

unknown commented at 10:37 PM on February 11, 2021:

Interesting. Curious about the reason because this will only connect to peers via Tor.

sipa commented at 11:18 PM on February 11, 2021:

It's a trade-off. Only connecting out over Tor is more private of course when you combine it with no reachable IPv4/IPv6 address, in particular if you want to broadcast transactions without them being correlatable with your IP.

On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks (as Tor addresses have 0 cost to create, an attacker can just flood the network with 1000s of apparent Tor Bitcoin nodes, and have a high probability of receiving all outbound Tor connections a Tor-only node makes). This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to cost of getting IPs in many networks. It's also less a concern if you have -addnoded connections to trusted peers (even if they're onion addresses).

jonatack commented at 11:23 PM on February 11, 2021:

For example, search on "onlynet" in https://en.bitcoin.it/wiki/Setting_up_a_Tor_hidden_service

"not particularly recommended...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 only wish to give access to your node to other Tor users, do not use it. "

Edit: this comment is not a reply to @sipa's comment; I had not seen it yet.

unknown commented at 8:08 AM on February 12, 2021:

Thanks for the details. Will be helpful.

Removed in https://github.com/bitcoin/bitcoin/pull/21157/commits/99c1e1521018a3fa5e59bb0dce1ddd39d94cb3cb

in doc/tor.md:148 in 0a02968f1c outdated

 144 | @@ -146,6 +145,53 @@ password` (refer to the [Tor Dev
 145 |  Manual](https://2019.www.torproject.org/docs/tor-manual.html.en) for more
 146 |  details).
 147 |  
 148 | +## Example: Bitcoin Core Onion Service on Ubuntu 20.04.2 LTS

jonatack commented at 9:57 PM on February 11, 2021:

I'm not sure if this section is needed as it is somewhat redundant with the section just before, but maybe other reviewers think it is helpful. A suggestion for the header:

## Example: creating an onion service on Debian/Ubuntu systems

unknown commented at 10:42 PM on February 11, 2021:

Changed header. Maybe some content can be changed or rephrased but one example is required. I was considering adding Windows and Android with screenshots as well but then dropped the idea because others may not agree to it.

in doc/tor.md:189 in 0a02968f1c outdated

 184 | +
 185 | +  ```
 186 | +  localaddresses": [
 187 | +    {
 188 | +      "address": "omy7kj7zwvfg5luayideh73uqb2latkoyyy5h65y4atv3fymnlxlzwqd.onion",
 189 | +      "port": 18333,

jonatack commented at 10:01 PM on February 11, 2021:

      "port": 8333,

in doc/tor.md:160 in 0a02968f1c outdated

 155 | +
 156 | +   Setup Control Port:
 157 | +
 158 | +  `sudo nano /etc/tor/torrc`
 159 | +
 160 | +  Add below lines and save:

jonatack commented at 10:07 PM on February 11, 2021:

These lines are usually already present (as explained above)

  Ensure that `torrc` has these settings, and save:

in doc/tor.md:33 in 0a02968f1c outdated

  28 | @@ -29,9 +29,8 @@ outgoing connections, but more is possible.
  29 |      -onion=ip:port  Set the proxy server to use for Tor onion services. You do not
  30 |                      need to set this if it's the same as -proxy. You can use -onion=0
  31 |                      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.
  35 | +
  36 | +**Note:** _Only the -proxy option sets the proxy for DNS requests with -onion they will not route over Tor, so use -proxy if you have privacy concerns._

jonatack commented at 10:09 PM on February 11, 2021:

missing semi-colon

**Note:** _Only the -proxy option sets the proxy for DNS requests; with -onion they will not route over Tor, so use -proxy if you have privacy concerns._

in doc/tor.md:167 in 0a02968f1c outdated

 162 | +  ```
 163 | +  ControlPort 9051
 164 | +  CookieAuthentication 1
 165 | +  CookieAuthFileGroupReadable 1
 166 | +  ```
 167 | +  Add user('satoshi' in this example) to Tor group:

jonatack commented at 10:11 PM on February 11, 2021:

  Add user ("satoshi" in this example) to the Tor group:

in doc/tor.md:269 in 0a02968f1c outdated

 264 | +  in China and India
 265 | +
 266 | +- If someone is operating in paranoid mode then the correct move is to not
 267 | +  listen at all on the node they are trying to protect, because any listening
 268 | +  lets attackers actively connect into them. Frequently changing local onion
 269 | +  address will not be helpful.

jonatack commented at 10:12 PM on February 11, 2021:

I'm not sure about this content, will let other reviewers weigh in.

unknown commented at 10:48 PM on February 11, 2021:

This was mentioned by Greg Maxwell when we were discussing about adding an option that deletes "onion private key" regularly: #17491 (comment)

jonatack commented at 11:20 PM on February 11, 2021:

I agree with Greg; am less sure about the rest of the two paragraphs and the writing could be improved, but better for others to weigh in.

sipa commented at 11:24 PM on February 11, 2021:

I think this is formulated strangely. Sure, frequently changing onion addresses is silly, but nothing in this document is suggesting doing that. You're also not defining what "paranoid mode" means.

What about this instead?

For maximal privacy, not listening at all is preferable over creating a hidden service.

unknown commented at 8:14 AM on February 12, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/pull/21157/commits/46329146b3c111490960bf4072c83b3f9015a9c1 and replaced with:

For maximal privacy, not listening at all is preferable over creating an onion service.

Since we have not mentioned about deleting "Onion Private Key" in this doc, maybe its best to edit the Bitcoin Wiki to remove or change that line: https://en.bitcoin.it/w/index.php?title=Setting_up_a_Tor_hidden_service

jonatack commented at 10:12 PM on February 11, 2021: member

Some suggestions below.

jonatack commented at 11:27 PM on February 11, 2021: member

(p.s. thank you, it's very kind, but no need to add me as a co-author just for reviewing)

DrahtBot added the label Docs on Feb 11, 2021

Saibato commented at 11:36 AM on February 12, 2021: contributor

tACK https://github.com/bitcoin/bitcoin/pull/21157/commits/056ad79f3899272a2c2b0583f4c9953bbb7387bc

nit, Maybe u can add a followup PR? And electorate further a max privacy ( probable dual node remote Tor service ) config, and the subsequent config steps. since by default a node will listen for clearnet and Tor connections. And service ( if that became or is possible, instantly even later on the fly i.e when the node runs and a user would just install first time Tor or enable it, while a default configed node is running ) in and outbound pure Tor onions, while all dns (UDP) and gossip (TCP) will still route over ip4/6.

For maximal privacy, not listening at all is preferable over creating an onion service

ghost commented at 2:05 PM on February 12, 2021: none

And electorate further a max privacy ( probable dual node remote Tor service ) config, and the subsequent config steps. since by default a node will listen for clearnet and Tor connections. And service ( if that became or is possible, instantly even later on the fly i.e when the node runs and a user would just install first time Tor or enable it, while a default configed node is running ) in and outbound pure Tor onions, while all dns (UDP) and gossip (TCP) will still route over ip4/6.

This looks interesting but I think we can do this in a new PR together if you could share more details with me on Twitter or Reddit I will experiment with things and let you know.

in doc/tor.md:263 in 056ad79f38 outdated

 255 | @@ -211,3 +256,11 @@ for normal IPv4/IPv6 communication, use:
 256 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 257 |    services created automatically (as in section 2) always have only one port
 258 |    open.
 259 | +
 260 | +- If you are in an environment that does not permit direct Tor connections,
 261 | +  and does not permit the public bridges, then considering the trade-offs
 262 | +  it probably isn't safe enough to use the Tor network. Example: few places
 263 | +  in China and India

jonatack commented at 3:16 PM on February 12, 2021:

It may be more maintainable to not cite specific countries or regions, as situations can change.

Writing suggestion:

If you are in an environment that does not permit direct Tor connections or public bridges, it may not be safe enough to use the Tor network.

Saibato commented at 4:42 PM on February 12, 2021:

who cares? Doc's are changing too, and those two county's deserve to be called out now. imho. I am glad to put this PR on my alert and TODO list and hail them for change instantly.

I know young devs ( not u ) have problems with dev or promoting Tor and calling out autocratic states and none of those devs must feel tempted to ACK here, but I had my life and can do this and give a s**t if that is polite or not, if it is a fact.

unknown commented at 5:11 PM on February 12, 2021:

I had mentioned those two countries in this Q&A on Stackexchange: https://bitcoin.stackexchange.com/questions/98772/what-are-the-safe-ways-to-connect-to-bitcoin-network-using-tor

I found few things mentioned in an article about Tor issues and since I am from India I was aware of some incidents here.

One example from China: http://www.asianews.it/news-en/Beijing-arrests-engineer-who-tried-to-bypass-Internet-censorship-32691.html

One example from India: https://www.newslaundry.com/2020/03/05/kashmiris-use-vpn-to-skirt-internet-curbs-but-is-vpn-really-secure

Censorship in some parts of India is not only limited to Tor, VPN, speed of Internet etc. but a lot of times Internet is completely shutdown in last few years for days in some places: https://internetshutdowns.in/ (Text messages work during such times so I had also worked on a side project to broadcast bitcoin transaction without Internet: https://github.com/prayank23/OfflineTx but thats not related to this PR)

jarolrod commented at 7:11 PM on February 26, 2021:

It's not a 'few places' in China and India; it is China and India as a whole. As you mentioned, you were aware of an incident. Others in your country may not be aware. It is better to include some warning in this doc to what we can here to prevent another incident. The part of the text does need a little work.

From:

If you are in an environment that does not permit direct Tor connections, and does not permit the public bridges, then considering the trade-offs it probably isn't safe enough to use the Tor network. Example: few places in China and India

To:

Some states have the ability to monitor and block use of the Tor network. Recent examples include China and India. If you are in an environment that does not permit direct Tor connections or the use of Tor bridges, then considering the trade-offs, it may not be safe to use the Tor network.

unknown commented at 6:48 PM on March 9, 2021:

Removed China and India.

in doc/tor.md:265 in 056ad79f38 outdated

 260 | +- If you are in an environment that does not permit direct Tor connections,
 261 | +  and does not permit the public bridges, then considering the trade-offs
 262 | +  it probably isn't safe enough to use the Tor network. Example: few places
 263 | +  in China and India
 264 | +
 265 | +- For maximal privacy, not listening at all is preferable over creating an

jonatack commented at 3:17 PM on February 12, 2021:

- For maximal privacy, disabling listening may be preferable to running an

jonatack commented at 3:20 PM on February 12, 2021: member

A couple more comments below.

Given the number of times I've seen people think the onlynet=tor is the only good option (e.g. the GUI pull that would only display the onion icon if all peers are onion peers), it would seem valuable to add some of the points mentioned by @sipa or maybe the wiki I linked, but that could also be done in a different pull.

ghost commented at 5:11 PM on February 12, 2021: none

it would seem valuable to add some of the points mentioned by @sipa or maybe the wiki I linked, but that could also be done in a different pull

Sure. We can add some of the things mentioned above about onlynet=onion

Maybe in "Privacy Recommendations"? Can include few important points mentioned by @sipa and @jonatack

Not sure what exactly should be the sentences and if this PR or a new PR.

RiccardoMasutti commented at 12:55 PM on February 15, 2021: contributor

I think we should also talk about torsocks and advice users to download packages with it:

Torsocks is a torifying wrapper that is primarily used to redirect all the network traffic of individual SOCKS-friendly applications through the Tor network. It also ensures DNS queries are handled correctly and explicitly blocks all UDP traffic from the application in question. Torsocks is the successor of tsocks and is still actively maintained. It is simply packaged as torsocks and is available (and often automatically included with the tor package) in many *nix based distributions.

ghost commented at 3:52 PM on February 15, 2021: none

I think we should also talk about torsocks and advice users to download packages with it:

Sure. Let me add this and other things suggested above by sipa and jonatack.

ghost commented at 11:07 PM on February 15, 2021: none

I have added things suggested by @sipa and @jonatack related to usage of onlynet=onion and downloading packages using torsocks suggested by @RiccardoMasutti as privacy recommendations in https://github.com/bitcoin/bitcoin/pull/21157/commits/c3f2243100c518fb52ba0f65874dad8e51de6b80

in doc/tor.md:268 in c3f2243100 outdated

 263 | +  in China and India
 264 | +
 265 | +- For maximal privacy, disabling listening may be preferable to running an
 266 | +  onion service.
 267 | +
 268 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better privacy.

RiccardoMasutti commented at 11:17 PM on February 15, 2021:

- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.

RiccardoMasutti changes_requested

ghost commented at 12:00 PM on February 23, 2021: none

Let's make it less complicated by improving docs:

https://twitter.com/StopAndDecrypt/status/1363977828291784706

in doc/tor.md:148 in ea00a788ea outdated

 144 | @@ -146,6 +145,52 @@ password` (refer to the [Tor Dev
 145 |  Manual](https://2019.www.torproject.org/docs/tor-manual.html.en) for more
 146 |  details).
 147 |  
 148 | +## Example: creating an onion service on Debian/Ubuntu systems

jarolrod commented at 7:32 PM on February 26, 2021:

I would say you should move this to the bottom of the file as the final section. I would suppose the guide is for someone who has never set up a tor service for bitcoin or has very little experience using tor. Moving it to the bottom would mean this user has, hopefully, read the doc from top to bottom. Then, they can get on setting it up with an example.

jarolrod commented at 7:53 PM on February 26, 2021:

I would also refactor this whole section:

Current bullet formatting looks akward
Change the title so that a common naming format can be used if we want to add a guide for another system
- From: Example: creating an onion service on Debian/Ubuntu Systems
- To: Setup Guide: Debian/Ubuntu
Better explanations per each step

Here is how that would look. This is just a rough suggestion, so make contextual additions as you see fit:

Setup Guide: Debian/Ubuntu

Assuming you already have an installation of Bitcoin Core:

1. Install Tor:

To install Tor, run:

sudo apt install tor

2. Edit Tor configuration file:

open up the torrc file with your favorite text editor, this example uses the nano text editor:

sudo nano /etc/tor/torrc

Edit the torrc file so that it has these settings:

ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

3. Add user to Tor group:

sudo usermod -a -G debian-tor satoshi

4. Restart Tor

To restart Tor, run:

sudo systemctl restart tor

5. Edit Bitcoin configuration file

Open up the bitcoin.conf file with your favorite text editor. Edit the file so that it contains these settings:

listen=1
torcontrol=127.0.0.1:9051
debug=tor

6. Confirmation

You should be all set up to run a node through the Tor Network. You can confirm that everything is setup correctly by running the getnetworkinfo RPC command. The result should look something like this:

localaddresses": [
  {
    "address": "omy7kj7zwvfg5luayideh73uqb2latkoyyy5h65y4atv3fymnlxlzwqd.onion",
    "port": 8333,
    "score": 4
  }
]

unknown commented at 8:53 PM on February 28, 2021:

@jarolrod Made changes in https://github.com/bitcoin/bitcoin/pull/21157/commits/db59179fbddfb6cfb08365398fe53e862e57d845

jarolrod commented at 7:58 PM on February 26, 2021: member

Concept ACK, Some suggestions below. I still need to get to the additions in the Privacy recommendations section

in doc/tor.md:218 in db59179fbd outdated

 213 | +- Some states have the ability to monitor and block use of the Tor network.
 214 | +  Recent examples include China and India. If you are in an environment that
 215 | +  does not permit direct Tor connections or the use of Tor bridges, then
 216 | +  considering the trade-offs, it may not be safe to use the Tor network.
 217 | +
 218 | +- For maximal privacy, disabling listening may be preferable to running an

jarolrod commented at 2:08 AM on March 1, 2021:

- For maximum privacy, it is preferable to disable listening instead of running an

in doc/tor.md:221 in db59179fbd outdated

 216 | +  considering the trade-offs, it may not be safe to use the Tor network.
 217 | +
 218 | +- For maximal privacy, disabling listening may be preferable to running an
 219 | +  onion service.
 220 | +
 221 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.

jarolrod commented at 2:38 AM on March 1, 2021:

How does this fit into running a tor Bitcoin service? can you elaborate and clarify what purpose this serves in relation to a Bitcoin service

unknown commented at 12:01 AM on March 2, 2021:

We have only one file in doc for Tor so I think its okay to suggest users about downloading packages with torsocks as a privacy recommendation. Suggested by @RiccardoMasutti in this PR

laanwj commented at 2:16 PM on April 14, 2021:

I don't like recommending this here. What kind of packages? Also there are security trade-offs to downloading software over Tor (e.g . there have been MITM by exit node operators). No need to get into that here. Please keep it focused on how to use bitcoind with tor.

jonatack commented at 8:11 AM on April 22, 2021:

I agree this sentence raises more questions than it answers.

in doc/tor.md:242 in db59179fbd outdated

 237 | +
 238 | +## Setup Guide: Debian/Ubuntu
 239 | +
 240 | +Assuming you already have an installation of Bitcoin Core:
 241 | +
 242 | +1. Install Tor:

jarolrod commented at 2:59 AM on March 1, 2021:

For visual clarity, please make each section of the guide bold

**1. Install Tor:**

in doc/tor.md:223 in db59179fbd outdated

 218 | +- For maximal privacy, disabling listening may be preferable to running an
 219 | +  onion service.
 220 | +
 221 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.
 222 | +
 223 | +- Trade-offs involved in using `onlynet=onion`:

jarolrod commented at 4:47 AM on March 1, 2021:

Here is how I would re-word this section. I feel that this encapsulates what you want to get across:

Trade-offs of the `onlynet=onion` configuration option:

The privacy benefits of Tor are affected if a Tor-Bitcoin service node is reachable by IPv4/IPv6 nodes. Placing onlynet=onion in your bitcoin.conf file will ensure that your node only attempts to connect over the Tor network, thus maximizing the benefits of using Tor. The decision to use this option should consider the following trade-offs:

Sybil Attacks While Sybil attacks are a threat on clearnet networks, it is of greater concern on the Tor network. A node that only maintains connections over Tor is vulnerable to a Sybil attack because of the minimal cost of creating a Tor address. This minimal cost means that an attacker can flood the network with thousands of apparent Tor-Bitcoin nodes controlled by the attacker.

One way to mitigate this is by leaving out the onlynet=onion configuration option, which will allow connections to IPv4/IPv6 nodes. Clearnet IPs have a greater creation cost, making it harder for an attacker to carry out a successful Sybil attack.

Network Partitioning If every Tor-Bitcoin node ran using the onlynet=onion configuration option, no Tor node would communicate with the clearnet network. This would result in the Bitcoin network becoming partitioned. For the health of the Bitcoin network as a whole, some nodes must communicate among both clearnet and Tor. You can help prevent this scenario by excluding the onlynet=onion configuration option.

unknown commented at 12:08 AM on March 2, 2021:

No issues in rephrasing as long as we share important things with users in the docs. What are your thoughts on this suggestion? Cc: @sipa @jonatack

jonatack commented at 11:48 AM on March 2, 2021:

Now that I2P support is merged, adding another privacy network, this may need some updating.

PulpCattel commented at 1:56 PM on March 2, 2021:

Isn't the sybil concern partially mitigated, or at least changed, by the fact that Tor onion connection are anonymous? The attacker won't be able to pick you and sybil specifically you, potentially without you even knowing. The attacker will instead have to sybil the whole network, which is a much more complex and easier to spot thing.

Is correct to say that in this context there is a trade-off between targeted and non-targeted sybilling? And should it be mentioned?

unknown commented at 4:34 PM on March 2, 2021:

@jonatack which part? I2P will have a separate file i2p.md as discussed in other PR so this can still be focused on Tor and related things?

jonatack commented at 4:50 PM on March 2, 2021:

@jonatack which part?

The onlynet discussion and the "when to use/not use tor" discussion... tor is no longer the only privacy network bitcoind can use, so for example, running onlynet=tor along with onlynet=i2p may be worth discussing. There may be reasons to prefer running both over onlynet=tor alone.

unknown commented at 10:16 PM on March 2, 2021:

The onlynet discussion

Agree. This can be changed and will need comments from people who are more experienced to compare Tor and i2p usage in Bitcoin Core. TBH I have not used i2p much. Also not sure what should be added here and what will be included in i2p.md.

"when to use/not use tor" discussion

The line added in this PR focuses on Tor and Tor bridges so I don't think it should be changed (with or without i2p reasons to avoid Tor in some parts remains the same). Maybe we can add one more "Privacy Recommendation" later in other PR.

Quoting the exact line I am talking about (Privacy Recommendation 2):

Some states have the ability to monitor and block use of the Tor network. Recent examples include China and India. If you are in an environment that does not permit direct Tor connections or the use of Tor bridges, then considering the trade-offs, it may not be safe to use the Tor network.

tor is no longer the only privacy network bitcoind can use, so for example, running onlynet=tor along with onlynet=i2p may be worth discussing.

Agree Tor isnt the only option now but this PR and file tor.md is for Tor.

There may be reasons to prefer running both over onlynet=tor alone.

Maybe

unknown commented at 10:17 PM on March 2, 2021:

Is correct to say that in this context there is a trade-off between targeted and non-targeted sybilling? And should it be mentioned? @PulpCattel Not sure

unknown commented at 6:48 PM on March 9, 2021:

Made changes and added onlynet=i2p, also mentioned i2p as other option available for privacy in Bitcoin Core apart from Tor.

jarolrod commented at 4:48 AM on March 1, 2021: member

Some more suggestions on the Privacy Recommendation section. Also, you must squash your commits into one. Any further commits should also be squashed.

in doc/tor.md:250 in 142ba6090b outdated

 245 | +
 246 | +```
 247 | +sudo apt install tor
 248 | +```
 249 | +
 250 | +2. Edit Tor configuration file:

jarolrod commented at 12:49 AM on March 2, 2021:

Since you made the first section (1. Install Tor) bold, as I suggested in this comment: #21157 (review). You have to make all other sections of this guide bold as I also suggested in the comment. That means lines #250 (2. Edit Tor Configuration file:), #265 (3. Add user to Tor group ("satoshi" in this example):, #271 (4. Restart Tor), #279 (5. Edit Bitcoin configuration file), and #290 (6. Confirmation) must also go bold

**2. Edit Tor configuration file:**

unknown commented at 4:44 PM on March 2, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/pull/21157/commits/8a32230482f612bb6bb79eb18c249152fd5daae3

in doc/tor.md:213 in 55b0a5890c outdated

 208 | @@ -211,3 +209,96 @@ for normal IPv4/IPv6 communication, use:
 209 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 210 |    services created automatically (as in section 2) always have only one port
 211 |    open.
 212 | +
 213 | +- Some states have the ability to monitor and block use of the Tor network.

michaelfolkson commented at 11:30 AM on March 9, 2021:

nit: Perhaps instead of "Some states have the ability to monitor and block use of the Tor network."

In some regions of the world usage of the Tor network is monitored and/or blocked.

unknown commented at 6:47 PM on March 9, 2021:

Made changes.

in doc/tor.md:214 in 55b0a5890c outdated

 208 | @@ -211,3 +209,96 @@ for normal IPv4/IPv6 communication, use:
 209 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 210 |    services created automatically (as in section 2) always have only one port
 211 |    open.
 212 | +
 213 | +- Some states have the ability to monitor and block use of the Tor network.
 214 | +  Recent examples include China and India. If you are in an environment that

michaelfolkson commented at 11:35 AM on March 9, 2021:

nit: "Recent examples include China and India."

I'd rather take out specific examples of countries to make it softer. I don't think we want to be unnecessarily antagonistic to national governments for no upside. The priority for this PR is that users have access to good documentation on how to use Tor rather than documenting where those users likely are.

unknown commented at 6:46 PM on March 9, 2021:

Removed

michaelfolkson commented at 11:41 AM on March 9, 2021: contributor

Concept ACK. Just a couple of nits so far but this is looking good, thanks for working on this.

I'll follow the instructions at a later date and give some feedback on how easy they were to follow and if I feel they could be improved.

DrahtBot commented at 4:50 PM on March 15, 2021: member

🕵️ @harding has been requested to review this pull request as specified in the REVIEWERS file.

RiccardoMasutti approved

RiccardoMasutti commented at 6:10 PM on March 15, 2021: contributor

ACK. Nice job guys.

Willtech commented at 1:47 PM on March 20, 2021: contributor

torsocks seems to easily work with torsocks bitcoin-qt --listen=0 in my testing. Requires --listen=0

torsocks is included by default with sudo get install tor on any recent Fedora

Is it useful to tell people to install nyx if they wish to monitor Tor?
If we become Tor central is that bad?

I think we should also talk about torsocks and advice users to download packages with it:

ghost commented at 6:18 AM on March 21, 2021: none

Is it useful to tell people to install nyx if they wish to monitor Tor?

Yes. Looks interesting. Never used it before but tried today and best thing I like about is the description in FAQ:

Simple - because the Greek goddess of night is short and memorable. Terminal applications are handiest when they're brief and easy to type. Top, ssh, scp - anything longer is just begging to be aliased down.

Maybe we can have a mini nyx for bitcoind or new RPC. Although a new follow up PR would be better to increase the probability of getting things merged soon and make it easier for people to review.

If we become Tor central is that bad?

Can you explain this in detail?

in doc/tor.md:300 in 3c42b3c87b outdated

 295 | +```
 296 | +
 297 | +**6. Confirmation**
 298 | +
 299 | +You should be all set up to run a node through the Tor Network.
 300 | +You can confirm that everything is setup correctly by running the getnetworkinfo

jonatack commented at 2:05 PM on March 21, 2021:

You can confirm that everything is set up correctly by running the `getnetworkinfo`

("setup" is a noun, the verb is "set up")

in doc/tor.md:301 in 3c42b3c87b outdated

 296 | +
 297 | +**6. Confirmation**
 298 | +
 299 | +You should be all set up to run a node through the Tor Network.
 300 | +You can confirm that everything is setup correctly by running the getnetworkinfo
 301 | +RPC command. The result should contain address for onion service:

jonatack commented at 2:06 PM on March 21, 2021:

RPC command. The result should contain an address corresponding to your onion service:

in doc/tor.md:288 in 3c42b3c87b outdated

 283 | +sudo systemctl restart tor
 284 | +```
 285 | +
 286 | +**5. Edit Bitcoin configuration file**
 287 | +
 288 | +Open up the bitcoin.conf file with your favorite text editor.

jonatack commented at 2:08 PM on March 21, 2021:

Open the `bitcoin.conf` file with your text editor.

in doc/tor.md:259 in 3c42b3c87b outdated

 254 | +sudo apt install tor
 255 | +```
 256 | +
 257 | +**2. Edit Tor configuration file:**
 258 | +
 259 | +open up the `torrc` file with your favorite text editor, this example uses the `nano` text editor:

jonatack commented at 2:09 PM on March 21, 2021:

Open the `torrc` file with your text editor. This example uses nano:

in doc/tor.md:242 in 3c42b3c87b outdated

 237 | +  This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to cost of getting IPs in many
 238 | +  networks. It's also less a concern if you have `-addnode` connections to trusted peers (even if they're onion addresses).
 239 | +
 240 | +  **Network Partitioning**
 241 | +
 242 | +  If everyone used `onlynet=onion` nobody on the onion bitcoin chain would be able to communicate with the clearnet chain.

jonatack commented at 2:12 PM on March 21, 2021:

  If too many nodes use `onlynet=onion`, it could become difficult for onion nodes to communicate with clearnet nodes.

in doc/tor.md:235 in 3c42b3c87b outdated

 230 | +  in particular if you want to broadcast transactions without them being correlatable with your IP.
 231 | +
 232 | +  **Sybil Attacks**
 233 | +
 234 | +  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks
 235 | +  (as Tor addresses have 0 cost to create, an attacker can just flood the network with 1000s of apparent Tor

jonatack commented at 2:14 PM on March 21, 2021:

  As Tor addresses may be created at no cost, an attacker can potentially flood the network with many Tor

in doc/tor.md:236 in 3c42b3c87b outdated

 231 | +
 232 | +  **Sybil Attacks**
 233 | +
 234 | +  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks
 235 | +  (as Tor addresses have 0 cost to create, an attacker can just flood the network with 1000s of apparent Tor
 236 | +  Bitcoin nodes, and have a high probability of receiving all outbound Tor connections a Tor-only node makes).

jonatack commented at 2:15 PM on March 21, 2021:

  nodes and receive all of the outbound Tor connections an `onlynet=tor` node makes.

in doc/tor.md:225 in 3c42b3c87b outdated

 220 | +
 221 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.
 222 | +
 223 | +- Trade-offs involved in using `onlynet=onion`:
 224 | +
 225 | +  Placing onlynet=onion in your bitcoin.conf file will ensure that your node only attempts to connect over

jonatack commented at 2:16 PM on March 21, 2021:

  The `onlynet=onion` configuration option can potentially ensure the node only attempts to connect over

jonatack commented at 2:16 PM on March 21, 2021:

  The `onlynet=onion` configuration option can potentially ensure the node only attempts to connect over

(note, config options may be used on the command line as well as in the conf file)

in doc/tor.md:226 in 3c42b3c87b outdated

 221 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.
 222 | +
 223 | +- Trade-offs involved in using `onlynet=onion`:
 224 | +
 225 | +  Placing onlynet=onion in your bitcoin.conf file will ensure that your node only attempts to connect over
 226 | +  the Tor network, thus maximizing the benefits of using Tor. The decision to use this option should consider

jonatack commented at 2:17 PM on March 21, 2021:

  the Tor network. The decision to use this option should consider

in doc/tor.md:234 in 3c42b3c87b outdated

 229 | +  Only connecting over Tor is more private when you combine it with no reachable IPv4/IPv6 address,
 230 | +  in particular if you want to broadcast transactions without them being correlatable with your IP.
 231 | +
 232 | +  **Sybil Attacks**
 233 | +
 234 | +  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks

jonatack commented at 2:19 PM on March 21, 2021:

  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks.

in doc/tor.md:216 in 3c42b3c87b outdated

 208 | @@ -211,3 +209,103 @@ for normal IPv4/IPv6 communication, use:
 209 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 210 |    services created automatically (as in section 2) always have only one port
 211 |    open.
 212 | +
 213 | +- In some regions of the world usage of the Tor network is monitored and/or blocked.
 214 | +  If you are in an environment that does not permit direct Tor connections or the use
 215 | +  of Tor bridges, then considering the trade-offs, it may not be safe to use Tor. Other
 216 | +  options for privacy in Bitcoin Core: i2p.

jonatack commented at 2:21 PM on March 21, 2021:

  Another option for Bitcoin network privacy is to use I2P (option `i2p`).

jonatack commented at 2:23 PM on March 21, 2021: member

A few grammar fixups and suggestions.

jonatack commented at 2:27 PM on March 21, 2021: member

torsocks seems to easily work with torsocks bitcoin-qt --listen=0 in my testing. Requires --listen=0 * Is it useful to tell people to install nyx if they wish to monitor Tor?

Mentioning using nyz (and watch -netinfo, e.g. bitcoin-cli -netinfo help) as node network monitoring tools could be useful indeed.

ghost commented at 5:50 PM on March 21, 2021: none

A few grammar fixups and suggestions. @jonatack Thanks for the review. Made changes in https://github.com/bitcoin/bitcoin/pull/21157/commits/193f24c8b9b7d3b8c31f99e42b1511163aaaf492

in doc/tor.md:278 in 193f24c8b9 outdated

 269 | +```
 270 | +
 271 | +**3. Add user to Tor group ("satoshi" in this example):**
 272 | +
 273 | +```
 274 | +sudo usermod -a -G debian-tor satoshi

unknown commented at 5:41 PM on March 27, 2021:

I think we will get permission error if we don't reboot system after adding user to Tor group. So maybe 4 can be replaced by sudo reboot. Let me know if you test these steps on Ubuntu @michaelfolkson

Willtech commented at 8:34 AM on April 2, 2021:

The note to reboot after using usermod exists in the latest commit e1604b3 from Feb 4.

ghost commented at 2:55 PM on March 28, 2021: none

~~I won't be active anymore. This is my only PR open in Bitcoin Core. Maintainers can close it or keep it open based on process followed.~~

~~Thanks everyone.~~

Reopened PR. Will update with one change discussed above about reboot

Willtech commented at 8:36 AM on April 2, 2021: contributor

Concept ACK Need to re-check the proposed merge e.g. #21157 (review)

in doc/tor.md:216 in 193f24c8b9 outdated

 208 | @@ -211,3 +209,102 @@ for normal IPv4/IPv6 communication, use:
 209 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 210 |    services created automatically (as in section 2) always have only one port
 211 |    open.
 212 | +
 213 | +- In some regions of the world usage of the Tor network is monitored and/or blocked.
 214 | +  If you are in an environment that does not permit direct Tor connections or the use
 215 | +  of Tor bridges, then considering the trade-offs, it may not be safe to use Tor.
 216 | +  Another option for Bitcoin network privacy is to use I2P (option `i2p`).

Willtech commented at 8:38 AM on April 2, 2021:

What is I2P (option i2p)?

jonatack commented at 8:46 AM on April 2, 2021:

I2P is the Invisible Internet Project, a second privacy network that was added to Bitcoin Core for the upcoming release.

I've written some docs for an initial doc/i2p.md file here, just need to overcome my desire to avoid bikeshedding to propose it 😛

harding commented at 3:45 PM on April 14, 2021:

I interpret this paragraph as advice to people to be careful in regions where Tor is legally disallowed or discouraged. I would suspect that places that legally ban Tor also legally ban I2P, so I think the final sentence here is a bit out of place---it seems to suggest that people who can't use Tor for legal reasons can use I2P.

I'd suggest rewriting the paragraph to encompass both options. E.g.: "In some regions of the world usage of privacy networks such as Tor or I2P (option: i2p) in monitored or blocked...it may notbe safe to use Tor or I2P."

unknown closed this on Apr 3, 2021

fanquake added the label Up for grabs on Apr 3, 2021

unknown reopened this on Apr 11, 2021

laanwj commented at 2:14 PM on April 14, 2021: member

Maybe we can have a mini nyx for bitcoind or new RPC. Although a new follow up PR would be better to increase the probability of getting things merged soon and make it easier for people to review.

FWIW there are various wonderful terminal tools to monitor a bitcoind node, for example bitcoind-ncurses and pyblock. But I'm not really in favor of mentioning them in the repository, I haven't vetted this software, and don't want to maintain a list of them, it's typically more of a wiki thing.

in doc/tor.md:219 in 6256401c11 outdated

 214 | +  If you are in an environment that does not permit direct Tor connections or the use
 215 | +  of Tor bridges, then considering the trade-offs, it may not be safe to use Tor.
 216 | +  Another option for Bitcoin network privacy is to use I2P (option `i2p`).
 217 | +
 218 | +- For maximum privacy, it is preferable to disable listening instead of running an
 219 | +  onion service.

harding commented at 3:49 PM on April 14, 2021:

I think "listening" in this context is a technical term readers might not understand. I suggest replacing with "disable accepting incoming connections".

unknown commented at 6:23 AM on April 16, 2021:

I interpret this paragraph as advice to people to be careful in regions where Tor is legally disallowed or discouraged. I would suspect that places that legally ban Tor also legally ban I2P

Agree. Governments consider use of Tor or i2p or VPN same in such places. Initially i2p was not mentioned, i2p was recently merged and it was suggested that we can mention it as an alternative here. #21157 (review)

I think "listening" in this context is a technical term readers might not understand. I suggest replacing with "disable accepting incoming connections".

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/16db258eafa21328b9433c2da6dce6fbc8f532de

harding commented at 8:09 PM on April 21, 2021:

I continue to believe this is not the correct location to mention I2P. I think putting it here gives the misleading impression that I2P has a different legal status than Tor. My personal suggestion would be to remove the I2P mention for now, wait for a PR adding I2P docs to be added, and then cross link the two documents from their opening paragraphs (i.e. Tor doc links to I2P doc; I2P doc links to Tor doc).

That said, I don't feel strongly enough about this for it to be a blocker.

unknown commented at 11:11 PM on April 21, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/bef89aff859849a64121f039cbdbb81468c9a455

in doc/tor.md:236 in 6256401c11 outdated

 232 | +
 233 | +  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks.
 234 | +  As Tor addresses may be created at no cost, an attacker can potentially flood the network with many Tor
 235 | +  nodes and receive all of the outbound Tor connections an `onlynet=tor` node makes.
 236 | +  This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to cost of getting IPs in many
 237 | +  networks. It's also less a concern if you have `-addnode` connections to trusted peers (even if they're onion addresses).

harding commented at 3:56 PM on April 14, 2021:

This paragraph should describe to consequence of a user being sybil attacked. E.g., add a third sentence: "If all of your connections are controlled by a Sybil attacker, they can easily prevent you from seeing confirmed transactions and, with more difficulty, even trick your node into falsely reporting a transaction as confirmed on the best block chain." (Obviously a sybil attacker can do other things too, like poison your addrman to make escaping the sybil impossible, but I don't think we need to go into all that detail.)

unknown commented at 6:24 AM on April 16, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/16db258eafa21328b9433c2da6dce6fbc8f532de However I mentioned blockchain with most cumulative “chainwork” instead of best block chain

in doc/tor.md:241 in 6256401c11 outdated

 236 | +  This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to cost of getting IPs in many
 237 | +  networks. It's also less a concern if you have `-addnode` connections to trusted peers (even if they're onion addresses).
 238 | +
 239 | +  **Network Partitioning**
 240 | +
 241 | +  If too many nodes use `onlynet=onion`, it could become difficult for onion nodes to communicate with clearnet nodes.

harding commented at 3:58 PM on April 14, 2021:

Although this does descibe the consequences, I think it could be a bit clearer. E.g.: "... communicate with clearnet nodes, preventing the Tor network from seeing recent transactions and blocks."

RiccardoMasutti commented at 8:33 AM on April 15, 2021:

  If too many nodes use `onlynet=onion`, it could become difficult for onion nodes to communicate with clearnet nodes, preventing them to stay in sync with the rest of the network.

unknown commented at 6:24 AM on April 16, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/16db258eafa21328b9433c2da6dce6fbc8f532de

unknown commented at 6:25 AM on April 16, 2021:

Done. Made changes according to #21157 (review)

in doc/tor.md:285 in 6256401c11 outdated

 280 | +sudo reboot
 281 | +```
 282 | +
 283 | +**5. Edit Bitcoin configuration file**
 284 | +
 285 | +Open the `bitcoin.conf` file with your text editor.

harding commented at 4:04 PM on April 14, 2021:

This should probably at least link to instructions about where to find your configuration directory, e.g. https://en.bitcoin.it/wiki/Running_Bitcoin#Bitcoin.conf_Configuration_File

(Maybe an idea would be to have bitcoin -version or another option that can be run concurrent with the main program report the full path to the various used directories.)

unknown commented at 6:24 AM on April 16, 2021:

This should probably at least link to instructions about where to find your configuration directory, e.g. en.bitcoin.it/wiki/Running_Bitcoin#Bitcoin.conf_Configuration_File

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/16db258eafa21328b9433c2da6dce6fbc8f532de

(Maybe an idea would be to have bitcoin -version or another option that can be run concurrent with the main program report the full path to the various used directories.)

Maybe can add information about files in bitcoind -help results?

in doc/tor.md:301 in 6256401c11 outdated

 296 | +You should be all set up to run a node through the Tor Network.
 297 | +You can confirm that everything is set up correctly by running the `getnetworkinfo`
 298 | +RPC command. The result should contain an address corresponding to your onion service:
 299 | +
 300 | +```
 301 | +localaddresses": [

harding commented at 4:07 PM on April 14, 2021:

Opening quote missing from the RPC results.

Suggestion: show the getnetworkinfo RPC being run here using bitcoin-cli, e.g.:

$ bitcoin-cli getnetworkinfo
"localaddresses": [
...

jonatack commented at 4:15 PM on April 14, 2021:

yes, note that this is simpler if -netinfo is used instead of getnetworkinfo, it's a shorter command and the output is simpler to parse for humans

unknown commented at 6:25 AM on April 16, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/16db258eafa21328b9433c2da6dce6fbc8f532de

harding commented at 4:08 PM on April 14, 2021: contributor

LGTM. A few suggestions below, but no blockers. Thanks for improving this document!

in doc/tor.md:242 in 6256401c11 outdated

 237 | +  networks. It's also less a concern if you have `-addnode` connections to trusted peers (even if they're onion addresses).
 238 | +
 239 | +  **Network Partitioning**
 240 | +
 241 | +  If too many nodes use `onlynet=onion`, it could become difficult for onion nodes to communicate with clearnet nodes.
 242 | +  It is essential that some nodes access both clearnet and Tor or use `onlynet=i2p` with `onlynet=onion`.

RiccardoMasutti commented at 8:28 AM on April 15, 2021:

  It is essential that some nodes access both clearnet and Tor, or use `onlynet=i2p` with `onlynet=onion`.

unknown commented at 6:25 AM on April 16, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/16db258eafa21328b9433c2da6dce6fbc8f532de I did some research about use of comma before or in any sentence and found that sometimes Programming Languages are easier to understand compared to English.

RiccardoMasutti changes_requested

RiccardoMasutti approved

RiccardoMasutti commented at 12:54 PM on April 18, 2021: contributor

ACK 16db258

in doc/tor.md:235 in bef89aff85 outdated

 230 | +
 231 | +  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks.
 232 | +  As Tor addresses may be created at no cost, an attacker can potentially flood the network with many Tor
 233 | +  nodes and receive all of the outbound Tor connections an `onlynet=tor` node makes.
 234 | +
 235 | +  This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to cost of getting IPs in many

jonatack commented at 8:03 AM on April 22, 2021:

  This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to the cost of obtaining IPs in many

unknown commented at 4:50 PM on April 26, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/6bf33db373588582c85ee537cd5e9302c593cb02

in doc/tor.md:236 in bef89aff85 outdated

 231 | +  On the other hand, if you only make random Tor connections, you're much more vulnerable to Sybil attacks.
 232 | +  As Tor addresses may be created at no cost, an attacker can potentially flood the network with many Tor
 233 | +  nodes and receive all of the outbound Tor connections an `onlynet=tor` node makes.
 234 | +
 235 | +  This is significantly less a concern with IPv4/IPv6 (especially with asmap) due to cost of getting IPs in many
 236 | +  networks. It's also less a concern if you have `-addnode` connections to trusted peers (even if they're onion addresses).

jonatack commented at 8:04 AM on April 22, 2021:

  networks. It's also alleviated if you make `-addnode` connections to trusted peers (even if they're onion addresses).

unknown commented at 4:50 PM on April 26, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/6bf33db373588582c85ee537cd5e9302c593cb02

in doc/tor.md:213 in bef89aff85 outdated

 208 | @@ -211,3 +209,105 @@ for normal IPv4/IPv6 communication, use:
 209 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 210 |    services created automatically (as in section 2) always have only one port
 211 |    open.
 212 | +
 213 | +- In some regions of the world usage of the Tor network is monitored and/or blocked.

jonatack commented at 8:04 AM on April 22, 2021:

- In some regions of the world the Tor network is monitored or blocked.

unknown commented at 4:50 PM on April 26, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/6bf33db373588582c85ee537cd5e9302c593cb02

in doc/tor.md:33 in bef89aff85 outdated

  28 | @@ -29,9 +29,8 @@ outgoing connections, but more is possible.
  29 |      -onion=ip:port  Set the proxy server to use for Tor onion services. You do not
  30 |                      need to set this if it's the same as -proxy. You can use -onion=0
  31 |                      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.
  35 | +
  36 | +**Note:** _Only the -proxy option sets the proxy for DNS requests; with -onion they will not route over Tor, so use -proxy if you have privacy concerns._

jonatack commented at 8:08 AM on April 22, 2021:

This change breaks up the formatting. I think it is better in the -onion section where it is currently and where it directly relates.

unknown commented at 4:51 PM on April 26, 2021:

Sorry I don't agree with this. I tried different things to highlight this part so that a user reading this doc for the first time do not miss this information. Or it will be helpful if you could suggest me a better way to highlight this.

jonatack commented at 2:14 PM on May 3, 2021:

it will be helpful if you could suggest me a better way to highlight this.

Sure! Can you keep the current position and italicize this part or use bold characters to highlight it? This is a list of config options and it would be good to not break it up in the middle.

unknown commented at 5:30 AM on May 6, 2021:

I couldn't find a way to use italic or bold in a code block indented with four spaces.

unknown commented at 5:38 AM on May 6, 2021:

2 config options to set proxy
Highlighted text about those options
Other config options below

LGTM

jonatack commented at 7:14 AM on May 6, 2021:

If you really want to pull out this text, why not place it at the top or the bottom of the list? Still, as this text refers to the -onion option, in my opinion it should remain there.

jonatack commented at 4:41 PM on June 2, 2021:

Do you plan to address this?

unknown commented at 4:55 PM on June 2, 2021:

I am not sure if there is any other better way to highlight this. Top and Bottom will not be useful. A newbie or even a power user needs to read this while going to through proxy options. Highlighting DNS was one of the important parts of this PR (mentioned in description) as I have seen lot of people ignore it and DNS leaks affecting their privacy.

jonatack commented at 5:07 PM on June 2, 2021:

I think it's in the right place already.

harding commented at 10:36 PM on June 2, 2021:

This adds the bold formatting as @jonatack requested: https://github.com/harding/bitcoin/blob/095310798bc0622498515cf6d5c772a01c60c7c5/doc/tor.md

diff --git a/doc/tor.md b/doc/tor.md
index 2640a6109..31fa4f554 100644
--- a/doc/tor.md
+++ b/doc/tor.md
@@ -25,6 +25,7 @@ knows when upgrading to current and future Tor releases that support Tor v3 only
 The first step is running Bitcoin Core behind a Tor proxy. This will already anonymize all
 outgoing connections, but more is possible.
 
+<pre>
     -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.
                     You need to use -noonion or -onion=0 to explicitly disable
@@ -33,7 +34,7 @@ outgoing connections, but more is possible.
     -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 -onion=0
                     to explicitly disable access to onion services.
-                    Note: Only the -proxy option sets the proxy for DNS requests;
+                    <b>Note:</b> Only the -proxy option sets the proxy for DNS requests;
                     with -onion they will not route over Tor, so use -proxy if you
                     have privacy concerns.
 
@@ -54,6 +55,7 @@ outgoing connections, but more is possible.
                     connections will be enabled when you use -proxy or -onion. Use
                     -noonion or -onion=0 if you want to be sure there are no outbound
                     onion connections over the default proxy or your defined -proxy.
+</pre>
 
 In a typical situation, this suffices to run behind a Tor proxy:

unknown commented at 11:01 PM on June 2, 2021:

Cool. I will make this change. I was trying bold and italic without <pre></pre> tags

unknown commented at 11:12 PM on June 2, 2021:

Implemented the suggestion in https://github.com/bitcoin/bitcoin/commit/a51c1b795544238f534c7273c9382357e44b05a6 Thanks for helping with the tags I was missing

in doc/tor.md:224 in bef89aff85 outdated

 219 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.
 220 | +
 221 | +- Trade-offs involved in using `onlynet=onion`:
 222 | +
 223 | +  The `onlynet=onion` configuration option can potentially ensure the node only attempts to connect over
 224 | +  the Tor network. The decision to use this option should consider the following trade-offs:

jonatack commented at 8:13 AM on April 22, 2021:

The first sentence is repeating the onlynet docs, but less precisely. The second sentence repeats the bullet point. Suggest dropping this paragraph completely. Brevity is good.

unknown commented at 4:51 PM on April 26, 2021:

The first sentence is repeating the onlynet docs

Which docs?

The second sentence repeats the bullet point.

Removed it.

jonatack commented at 7:16 AM on May 6, 2021:

The first sentence is repeating the onlynet docs

Which docs?

The description in the list of options.

unknown commented at 4:27 PM on June 2, 2021:

Made changes in https://github.com/bitcoin/bitcoin/commit/cb46911a3b09f126eeb40e02234d8ca57757e3d6

in doc/tor.md:301 in bef89aff85 outdated

 296 | +```
 297 | +
 298 | +**6. Confirmation**
 299 | +
 300 | +You should be all set up to run a node through the Tor Network.
 301 | +You can confirm that everything is set up correctly by using `getnetworkinfo` or `-netinfo`

jonatack commented at 8:20 AM on April 22, 2021:

You can confirm that everything is set up correctly by running `getnetworkinfo` or `-netinfo` and checking that the local addresses they return include the onion service.

This would allow dropping the rest after this.

unknown commented at 4:51 PM on April 26, 2021:

Done. Made changes in https://github.com/bitcoin/bitcoin/commit/6bf33db373588582c85ee537cd5e9302c593cb02

in doc/tor.md:284 in bef89aff85 outdated

 279 | +```
 280 | +
 281 | +**4. Restart System**
 282 | +
 283 | +```
 284 | +sudo reboot

jonatack commented at 8:24 AM on April 22, 2021:

I think you can drop the sudo instructions in this section. They are context-dependent.

unknown commented at 4:51 PM on April 26, 2021:

As mentioned in this answer: https://askubuntu.com/a/1006034, sudo is used in most of the tutorials for compatibility reasons and these steps in the example are included for all newbies who are trying Bitcoin Core with Tor for the first time on Ubuntu or other Debian based Linux distributions.

jonatack commented at 8:32 AM on April 22, 2021: member

A few comments after re-reviewing. Some parts seem a bit redundant or verbose; don't hesitate to tighten them up.

in doc/tor.md:270 in 6bf33db373 outdated

 265 | +sudo nano /etc/tor/torrc
 266 | +```
 267 | +Ensure that `torrc` has these settings, and save:
 268 | +
 269 | +```
 270 | +ControlPort 9051

rebroad commented at 1:27 PM on May 3, 2021:

In my experience this was the only line needed. I haven't needed the following two lines on any of my nodes.

unknown commented at 6:51 PM on May 5, 2021:

listen is 1 by default except if proxy is used so maybe we can remove this line or add proxy as well.

debug=tor is for logs

unknown commented at 8:46 PM on June 7, 2021:

@rebroad Just realized this comment was about Tor config file. Sorry earlier I thought its about torcontrol in bitcoin.conf

Are you using torpassword in bitcoin.conf?

rebroad commented at 1:30 PM on May 3, 2021: contributor

Have you mentioned the importance of using Tor version 4? Ideally it would be nice if bitcoin-qt could pop up an alert to the user if the tor version is too old to be useable.

michaelfolkson commented at 5:27 PM on May 4, 2021: contributor

@rebroad:

Have you mentioned the importance of using Tor version 4?

What is the importance of using Tor version 4? It is important to use Tor v3 addresses as v2 addresses are EOL but beyond that I'm not clear on the importance of using Tor version 4. Some critical bug fixes?

ghost commented at 6:57 PM on May 5, 2021: none

Have you mentioned the importance of using Tor version 4?

Latest Tor version is 0.4.5.7 according to https://www.torproject.org/download/tor/

Ideally it would be nice if bitcoin-qt could pop up an alert to the user if the tor version is too old to be useable.

I think this is a good suggestion and can be added with a new PR if others agree with it. I had some issues with Tor version once: https://github.com/bitcoin/bitcoin/issues/21147

laanwj removed the label Up for grabs on May 28, 2021

ghost commented at 4:35 PM on June 2, 2021: none

Added proxy in example and rephrased one trade-off according to the suggestion in #21157 (review)

Its been 4 months, PR reviewed by 11 people, almost every suggestion according to the scope of PR was acknowledged and made changes accordingly. Feel free to ACK/NACK so that we can merge this soon and improve Tor docs.

harding commented at 10:41 PM on June 2, 2021: contributor

ACK cb46911a3b09f126eeb40e02234d8ca57757e3d6 . Also implementing the suggestion in https://github.com/bitcoin/bitcoin/pull/21157/files#r644364143 would be fine (I don't think it matters either way)

Improve Tor docs

+ Highlight DNS requests part
+ Add 1 example in the end
+ Add 4 Privacy recommendations
+ Mention about `onlynet=i2p`

a51c1b7955

RiccardoMasutti approved

RiccardoMasutti commented at 8:25 AM on June 3, 2021: contributor

ACK a51c1b7

in doc/tor.md:226 in a51c1b7955

 221 | +- Users can download packages with [torsocks](https://gitlab.torproject.org/legacy/trac/-/wikis/doc/torsocks) for better security and privacy.
 222 | +
 223 | +- Trade-offs involved in using `onlynet=onion`:
 224 | +
 225 | +  The `onlynet=onion` configuration option can potentially ensure the node attempts to only
 226 | +  connect over Tor. It is more private when you combine it with no reachable IPv4/IPv6 address,

Rspigler commented at 11:00 PM on June 21, 2021:

perhaps put in parenthesis how this is achievable (bind=127.0.0.1:9050)?

Rspigler commented at 11:01 PM on June 21, 2021:

perhaps put in parenthesis how this is achievable (bind=127.0.0.1:9050)?

unknown commented at 4:07 AM on June 22, 2021:

Yes bind=onion can be mentioned

unknown commented at 1:14 AM on June 23, 2021:

This is already mentioned above in the docs

in doc/tor.md:246 in a51c1b7955

 241 | +
 242 | +  **Network Partitioning**
 243 | +
 244 | +  If too many nodes use `onlynet=onion`, it could become difficult for onion nodes to communicate with clearnet nodes,
 245 | +  preventing the Tor network from seeing recent transactions and blocks. It is essential that some nodes access both
 246 | +  clearnet and Tor, or use `onlynet=i2p` with `onlynet=onion`.

Rspigler commented at 11:03 PM on June 21, 2021:

link to i2p docs here?

unknown commented at 4:11 AM on June 22, 2021:

Sure I can use the link /doc/i2p.md

unknown commented at 1:14 AM on June 23, 2021:

Have added this in PR 22316

in doc/tor.md:248 in a51c1b7955

 243 | +
 244 | +  If too many nodes use `onlynet=onion`, it could become difficult for onion nodes to communicate with clearnet nodes,
 245 | +  preventing the Tor network from seeing recent transactions and blocks. It is essential that some nodes access both
 246 | +  clearnet and Tor, or use `onlynet=i2p` with `onlynet=onion`.
 247 | +
 248 | +## Setup Guide: Debian/Ubuntu

Rspigler commented at 11:05 PM on June 21, 2021:

Is this onward not just a duplication of lines 59-149? (Any changes should be edited in there).

unknown commented at 4:27 AM on June 22, 2021:

Lines 59-149 have lot of things in detail mentioned under <h2> header "Automatically create a Bitcoin Core onion service". The example here is just the basic steps required to quickly setup Bitcoin Core Onion Service on Ubuntu without going in to details and skipping whole documentation or fix things in case confused after reading everything written above.

What?

The goal here was to mention 3 examples: Ubuntu, Windows and Android similar to https://bitcoin.stackexchange.com/questions/98913/how-to-run-bitcoin-core-as-onion-service-on-windows-ubuntu-and-android/

Why?

There can be few users who refer to this doc but find everything mentioned confusing and give up somewhere in between or miss some important steps.
We should avoid users searching for proper documentation in different websites, forums, blogs etc. and everyone should be able to follow the things easily using doc in this repository. Privacy should not be hard to achieve or at least the first steps should be easy and encouraging enough to motivate the user in learning more later.

So, the example is basically to skip all the things mentioned above. Run the commands and setup Bitcoin Core Onion Service in few minutes. Once the user can see that onion address and things working it will motivate him to read all the things mentioned in doc if interested to research more.

How?

I have added only Ubuntu in this doc because I was expecting if I try to add everything in one PR it will never get merged. I think I was wrong and PR is anyways not merged and its been months. So, I can add more things or look for more ACKs in this to get merged and do follow up PRs later.

I can remove Line 293 and 294 if required to make the example even shorter and just the basic things one needs to try Bitcoin Core onion service quickly.

Rspigler commented at 5:58 PM on June 22, 2021:

We should avoid users searching for proper documentation in different websites, forums, blogs etc. and everyone should be able to follow the things easily using doc in this repository

I agree strongly with this.

However, I still don't understand why the steps are duplicated here (it is written differently, but the steps are the same).

edit torrc file
Set:

ControlPort 9051 CookieAuthentication 1 CookieAuthFileGroupReadable 1

Set up cookie authentication (add user to Tor group)

Your section "6. Confirmation" is duplicated in lines 8-16 (## How to see information about your Tor configuration via Bitcoin Core)

unknown commented at 1:13 AM on June 23, 2021:

Will plan on adding examples in a separate PR later. Appreciate your review and feedback.

in doc/tor.md:219 in a51c1b7955

 210 | @@ -211,3 +211,105 @@ for normal IPv4/IPv6 communication, use:
 211 |    Otherwise it is trivial to link them, which may reduce privacy. Onion
 212 |    services created automatically (as in section 2) always have only one port
 213 |    open.
 214 | +
 215 | +- In some regions of the world the Tor network is monitored or blocked.
 216 | +  If you are in an environment that does not permit direct Tor connections or the use
 217 | +  of Tor bridges, then considering the trade-offs, it may not be safe to use Tor.
 218 | +
 219 | +- For maximum privacy, it is preferable to disable accepting incoming connections.

Rspigler commented at 11:07 PM on June 21, 2021:

How would one disable incoming connections for an onion node? Running a HS requires listening to be set

Edit: With a proxied tor connection, that is the default. Maybe that is what is meant here?

unknown commented at 4:29 AM on June 22, 2021:

Edit: With a proxied tor connection, that is the default. Maybe that is what is meant here?

Yes

in doc/tor.md:252 in a51c1b7955

 247 | +
 248 | +## Setup Guide: Debian/Ubuntu
 249 | +
 250 | +Assuming you already have an installation of Bitcoin Core:
 251 | +
 252 | +**1. Install Tor:**

Rspigler commented at 6:00 PM on June 22, 2021:

you could move this to Line 20

unknown commented at 1:13 AM on June 23, 2021:

Will plan on adding examples in a separate PR later. Appreciate your review and feedback.

ghost commented at 1:16 AM on June 23, 2021: none

Thanks everyone for review. I am closing this PR in favor of alternative PRs: 22316 and 22317

Almost everything remains same. Feel free to ACK/NACK it. Keeping things separate so that one type of change doesn't keep the whole PR pending.

unknown closed this on Jun 23, 2021

DrahtBot commented at 5:12 AM on June 23, 2021: member

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#22317 (doc: Highlight DNS requests part in tor.md by prayank23)
#22316 (doc: Add 5 privacy recommendations in tor.md by prayank23)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

random-zebra referenced this in commit b4751e10ce on Aug 11, 2021

achow101 referenced this in commit 869c6e23c5 on Jan 18, 2022

sidhujag referenced this in commit f0028afd3e on Jan 18, 2022

DrahtBot locked this on Aug 16, 2022

doc: Improve Tor docs #21157

Setup Guide: Debian/Ubuntu

1. Install Tor:

2. Edit Tor configuration file:

3. Add user to Tor group:

4. Restart Tor

5. Edit Bitcoin configuration file

6. Confirmation

Trade-offs of the onlynet=onion configuration option:

Conflicts

Trade-offs of the `onlynet=onion` configuration option: