bitcoin-s/docs/tor/tor.md

---
id: tor
title: Tor Setup
---

It is possible to run Bitcoin-S through tor.
[Tor](https://www.torproject.org/) is an onion routed private network that allows us to send and receive messages in an
anonymous manner. Using tor in conjunction with Bitcoin-S allows you to be more private when syncing the blockchain, as
well as allows for sending and receiving DLC messages without the need for a static IP address or opening/forwarding of
ports.

## Installing Tor

### Debian

You can install tor using `sudo apt install tor` if on a debian system.

After installing you can start it with `sudo systemctl start tor`

### Brew

You can install tor using `brew install tor` if on a mac osx system.

After installing you can start it with `brew services start tor`

### Other

Otherwise, you can install the Tor Browser from [here](https://www.torproject.org/download/).

## Starting Tor

To connect to onion addresses you need to enable the tor proxy. To do so you need to have tor currently running, this
can be checked by using the command `sudo systemctl status tor`. This should give you an output similar to:

```bash
$ sudo systemctl status tor
● tor.service - Anonymizing overlay network for TCP (multi-instance-master)
     Loaded: loaded (/lib/systemd/system/tor.service; enabled; vendor preset: enabled)
     Active: active (exited) since Wed 2021-07-28 13:06:42 CDT; 48min ago
   Main PID: 804 (code=exited, status=0/SUCCESS)
      Tasks: 0 (limit: 18696)
     Memory: 0B
     CGroup: /system.slice/tor.service
```

If the output says `Active: active`, then it is running and good to go.

On mac osx you can use the command `brew services list` to ensure tor is running. This should give you an output similar to: 

```bash
$ brew services list
Name    Status  User        Plist            
tor     started $username /Users/username/Library/LaunchAgents/homebrew.mxcl.tor.plist 
```

If tor satus is `started`, then it is running and good to go. 

## Enabling the Tor proxy

Enabling the tor proxy allows you to create outgoing connections over tor. This is needed if you want to sync the
blockchain over tor, or to accept DLCs over tor.

To enable the tor proxy you simply need to set a couple config options after you have tor running.

You need to enable the proxy and set the host and port configuration options. If you are using the default settings you
should only need to set `bitcoin-s.proxy.enabled = true`.
These modifications need to be made to `$HOME/.bitcoin-s/bitcoin-s.conf` file.
Create this file if it does not exist.

```$xslt
bitcoin-s {
    proxy {
        # You can configure SOCKS5 proxy to use Tor for outgoing connections
        enabled = true
        sock5 = "127.0.0.1:9050"
    }
}
```

## Creating our own Tor hidden service

Enabling the tor hidden services allows for inbound connections over tor.
This is needed if you want to create DLCs over tor.

To enable the tor hidden services you need to set a couple config options after you have tor running in your bitcoin-s
config, as well as have tor configured for it.

### Configuring Tor

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` for linux or `/opt/homebrew/etc/tor/torcc` for mac, 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, `brew services restart tor` on mac osx, or just restart the
computer).

On some systems (such as Arch Linux), you may also need to add the following line:

```
DataDirectoryGroupReadable 1
```

You may also need permissions for the auth cookie file, this can be done doing

```bash
sudo usermod -a -G debian-tor $USER
```

After changing these settings, you will need to restart your computer.

### Configuring Bitcoin-S

You need to enable tor and set the control option, `127.0.0.1:9051` is the default. If you are using the default
settings you should only need to set `bitcoin-s.tor.enabled = true`.
These modifications need to be made to `$HOME/.bitcoin-s/bitcoin-s.conf` file.
Create this file if it does not exist.

```$xslt
bitcoin-s {
    tor {
        # You can enable Tor for incoming connections
        enabled = true
        control = "127.0.0.1:9051"

        # The password used to arrive at the HashedControlPassword for the control port.
        # If provided, the HASHEDPASSWORD authentication method will be used instead of
        # the SAFECOOKIE one.
        # password = securePassword

        # The path to the private key of the onion service being created
        # privateKeyPath = /path/to/priv/key
    }
}
```

### Manually Creating a Tor Hidden Service

Alternatively, you can manually create a tor hidden service.

You can also manually configure your node to be reachable from the Tor network. Add these lines to
your `/etc/tor/torrc` (or equivalent config file, mac is located at `/opt/homebrew/etc/tor/torcc`):

```
HiddenServiceDir /var/lib/tor/dlc-service/
HiddenServicePort 2862 127.0.0.1:2862
```

Then to get your host address simply do this after restarting your tor daemon.

```bash
sudo cat /var/lib/tor/dlc-service/hostname
```