91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# 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 Rendezvous 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.
|