vendor/github.com/btcsuite/btcd/docs/configuring_tor.md

   1 ### Table of Contents
   2 1. [Overview](#Overview)<br />
   3 2. [Client-Only](#Client)<br />
   4 2.1 [Description](#ClientDescription)<br />
   5 2.2 [Command Line Example](#ClientCLIExample)<br />
   6 2.3 [Config File Example](#ClientConfigFileExample)<br />
   7 3. [Client-Server via Tor Hidden Service](#HiddenService)<br />
   8 3.1 [Description](#HiddenServiceDescription)<br />
   9 3.2 [Command Line Example](#HiddenServiceCLIExample)<br />
  10 3.3 [Config File Example](#HiddenServiceConfigFileExample)<br />
  11 4. [Bridge Mode (Not Anonymous)](#Bridge)<br />
  12 4.1 [Description](#BridgeDescription)<br />
  13 4.2 [Command Line Example](#BridgeCLIExample)<br />
  14 4.3 [Config File Example](#BridgeConfigFileExample)<br />
  15 5. [Tor Stream Isolation](#TorStreamIsolation)<br />
  16 5.1 [Description](#TorStreamIsolationDescription)<br />
  17 5.2 [Command Line Example](#TorStreamIsolationCLIExample)<br />
  18 5.3 [Config File Example](#TorStreamIsolationFileExample)<br />
  19
  20 <a name="Overview" />
  21
  22 ### 1. Overview
  23
  24 btcd provides full support for anonymous networking via the
  25 [Tor Project](https://www.torproject.org/), including [client-only](#Client)
  26 and [hidden service](#HiddenService) configurations along with
  27 [stream isolation](#TorStreamIsolation).  In addition, btcd supports a hybrid,
  28 [bridge mode](#Bridge) which is not anonymous, but allows it to operate as a
  29 bridge between regular nodes and hidden service nodes without routing the
  30 regular connections through Tor.
  31
  32 While it is easier to only run as a client, it is more beneficial to the Bitcoin
  33 network to run as both a client and a server so others may connect to you to as
  34 you are connecting to them.  We recommend you take the time to setup a Tor
  35 hidden service for this reason.
  36
  37 <a name="Client" />
  38
  39 ### 2. Client-Only
  40
  41 <a name="ClientDescription" />
  42
  43 **2.1 Description**<br />
  44
  45 Configuring btcd as a Tor client is straightforward.  The first step is
  46 obviously to install Tor and ensure it is working. Once that is done, all that
  47 typically needs to be done is to specify the `--proxy` flag via the btcd command
  48 line or in the btcd configuration file.  Typically the Tor proxy address will be
  49 127.0.0.1:9050 (if using standalone Tor) or 127.0.0.1:9150 (if using the Tor
  50 Browser Bundle).  If you have Tor configured to require a username and password,
  51 you may specify them with the `--proxyuser` and `--proxypass` flags.
  52
  53 By default, btcd assumes the proxy specified with `--proxy` is a Tor proxy and
  54 hence will send all traffic, including DNS resolution requests, via the
  55 specified proxy.
  56
  57 NOTE: Specifying the `--proxy` flag disables listening by default since you will
  58 not be reachable for inbound connections unless you also configure a Tor
  59 [hidden service](#HiddenService).
  60
  61 <a name="ClientCLIExample" />
  62
  63 **2.2 Command Line Example**<br />
  64
  65 ```bash
  66 $ ./btcd --proxy=127.0.0.1:9050
  67 ```
  68
  69 <a name="ClientConfigFileExample" />
  70
  71 **2.3 Config File Example**<br />
  72
  73 ```text
  74 [Application Options]
  75
  76 proxy=127.0.0.1:9050
  77 ```
  78
  79 <a name="HiddenService" />
  80
  81 ### 3. Client-Server via Tor Hidden Service
  82
  83 <a name="HiddenServiceDescription" />
  84
  85 **3.1 Description**<br />
  86
  87 The first step is to configure Tor to provide a hidden service.  Documentation
  88 for this can be found on the Tor project website
  89 [here](https://www.torproject.org/docs/tor-hidden-service.html.en).  However,
  90 there is no need to install a web server locally as the linked instructions
  91 discuss since btcd will act as the server.
  92
  93 In short, the instructions linked above entail modifying your `torrc` file to
  94 add something similar to the following, restarting Tor, and opening the
  95 `hostname` file in the `HiddenServiceDir` to obtain your hidden service .onion
  96 address.
  97
  98 ```text
  99 HiddenServiceDir /var/tor/btcd
 100 HiddenServicePort 8333 127.0.0.1:8333
 101 ```
 102
 103 Once Tor is configured to provide the hidden service and you have obtained your
 104 generated .onion address, configuring btcd as a Tor hidden service requires
 105 three flags:
 106 * `--proxy` to identify the Tor (SOCKS 5) proxy to use for outgoing traffic.
 107   This is typically 127.0.0.1:9050.
 108 * `--listen` to enable listening for inbound connections since `--proxy`
 109   disables listening by default
 110 * `--externalip` to set the .onion address that is advertised to other peers
 111
 112 <a name="HiddenServiceCLIExample" />
 113
 114 **3.2 Command Line Example**<br />
 115
 116 ```bash
 117 $ ./btcd --proxy=127.0.0.1:9050 --listen=127.0.0.1 --externalip=fooanon.onion
 118 ```
 119
 120 <a name="HiddenServiceConfigFileExample" />
 121
 122 **3.3 Config File Example**<br />
 123
 124 ```text
 125 [Application Options]
 126
 127 proxy=127.0.0.1:9050
 128 listen=127.0.0.1
 129 externalip=fooanon.onion
 130 ```
 131
 132 <a name="Bridge" />
 133
 134 ### 4. Bridge Mode (Not Anonymous)
 135
 136 <a name="BridgeDescription" />
 137
 138 **4.1 Description**<br />
 139
 140 btcd provides support for operating as a bridge between regular nodes and hidden
 141 service nodes.  In particular this means only traffic which is directed to or
 142 from a .onion address is sent through Tor while other traffic is sent normally.
 143 _As a result, this mode is **NOT** anonymous._
 144
 145 This mode works by specifying an onion-specific proxy, which is pointed at Tor,
 146 by using the `--onion` flag via the btcd command line or in the btcd
 147 configuration file.  If you have Tor configured to require a username and
 148 password, you may specify them with the `--onionuser` and `--onionpass` flags.
 149
 150 NOTE: This mode will also work in conjunction with a hidden service which means
 151 you could accept inbound connections both via the normal network and to your
 152 hidden service through the Tor network.  To enable your hidden service in bridge
 153 mode, you only need to specify your hidden service's .onion address via the
 154 `--externalip` flag since traffic to and from .onion addresses are already
 155 routed via Tor due to the `--onion` flag.
 156
 157 <a name="BridgeCLIExample" />
 158
 159 **4.2 Command Line Example**<br />
 160
 161 ```bash
 162 $ ./btcd --onion=127.0.0.1:9050 --externalip=fooanon.onion
 163 ```
 164
 165 <a name="BridgeConfigFileExample" />
 166
 167 **4.3 Config File Example**<br />
 168
 169 ```text
 170 [Application Options]
 171
 172 onion=127.0.0.1:9050
 173 externalip=fooanon.onion
 174 ```
 175
 176 <a name="TorStreamIsolation" />
 177
 178 ### 5. Tor Stream Isolation
 179
 180 <a name="TorStreamIsolationDescription" />
 181
 182 **5.1 Description**<br />
 183
 184 Tor stream isolation forces Tor to build a new circuit for each connection
 185 making it harder to correlate connections.
 186
 187 btcd provides support for Tor stream isolation by using the `--torisolation`
 188 flag.  This option requires --proxy or --onionproxy to be set.
 189
 190 <a name="TorStreamIsolationCLIExample" />
 191
 192 **5.2 Command Line Example**<br />
 193
 194 ```bash
 195 $ ./btcd --proxy=127.0.0.1:9050 --torisolation
 196 ```
 197
 198 <a name="TorStreamIsolationFileExample" />
 199
 200 **5.3 Config File Example**<br />
 201
 202 ```text
 203 [Application Options]
 204
 205 proxy=127.0.0.1:9050
 206 torisolation=1
 207 ```