# Tor Support in Magic-Wormhole

The ``wormhole`` command-line tool has built-in support for performing
transfers over Tor. To use it, you must install with the "tor" extra,
like this:

```
pip install magic-wormhole[tor]
```

## Usage

Just add ``--tor`` to use a running Tor daemon:

```
wormhole send --tor myfile.jpg

wormhole receive --tor
```

You should use ``--tor`` rather than running ``wormhole`` under tsocks
or torsocks because the magic-wormhole "Transit" protocol normally sends
the IP addresses of each computer to its peer, to attempt a direct
connection between the two (somewhat like the FTP protocol would do).
External tor-ifying programs don't know about this, so they can't strip
these addresses out. Using ``--tor`` puts magic-wormhole into a mode
where it does not share any IP addresses.

``--tor`` causes the program to look for a Tor control port in the three
most common locations:

* ``unix:/var/run/tor/control``: Debian/Ubuntu Tor listen here
* ``tcp:localhost:9051``: the standard Tor control port
* ``tcp:localhost:9151``: control port for TorBrowser's embedded Tor

If ``wormhole`` is unable to establish a control-port connection to any
of those locations, it will assume there is a SOCKS daemon listening on
``tcp:localhost:9050``, and hope for the best (if no SOCKS daemon is
available on that port, the initial Mailbox connection will fail, and
the program will exit with an error before doing anything else).

The default behavior will Just Work if:

* you are on a Debian-like system, and the ``tor`` package is installed,
  or:
* you have launched the ``tor`` daemon manually, or:
* the TorBrowser application is running when you start ``wormhole``

On Debian-like systems, if your account is a member of the
``debian-tor`` group, ``wormhole`` will use the control-port to ask for
the right SOCKS port. If not, it should fall back to using the default
SOCKS port on 9050. To add your account to the ``debian-tor`` group, use
e.g. ``sudo adduser MYUSER debian-tor``. Access to the control-port will
be more significant in the future, when ``wormhole`` can listen on
"onion services": see below for details.

## Other Ways To Reach Tor

If ``tor`` is installed, but you cannot use the control-port or
SOCKS-port for some reason, then you can use ``--launch-tor`` to ask
``wormhole`` to start a new Tor daemon for the duration of the transfer
(and then shut it down afterwards). This will add 30-40 seconds to
program startup.

```
wormhole send --tor --launch-tor myfile.jpg
```

Alternatively, if you know of a pre-existing Tor daemon with a
non-standard control-port, you can specify that control port with the
``--tor-control-port=`` argument:

```
wormhole send --tor --tor-control-port=tcp:127.0.0.1:9251 myfile.jpg
```

## .onion servers

In the future, ``wormhole`` with ``--tor`` will listen on an ephemeral
"onion service" when file transfers are requested. If both sides are
Tor-capable, this will allow transfers to take place "directly" (via the
Tor network) from sender to receiver, bypassing the Transit Relay
server. This will require access to a Tor control-port (to ask Tor to
create a new ephemeral onion service). SOCKS-port access will not be
sufficient.

However the current version of ``wormhole`` does not use onion services.
For now, if both sides use ``--tor``, any file transfers must use the
transit relay, since neither side will advertise any listening IP
addresses.