851b7474d8
Thanks to @kaie in https://github.com/warner/magic-wormhole/issues/387 for the suggestion.
151 lines
6.4 KiB
Markdown
151 lines
6.4 KiB
Markdown
# Running the Transit Relay
|
|
|
|
First off, you probably don't need to run a relay. The ``wormhole`` command,
|
|
as shipped from magic-wormhole.io, is configured to use a default Transit
|
|
Relay operated by the author of Magic-Wormhole. This can be changed with the
|
|
``--transit-helper=`` argument, and other applications that import the
|
|
Wormhole library might point elsewhere.
|
|
|
|
The only reasons to run a separate relay are:
|
|
|
|
* You are a kind-hearted server admin who wishes to support the project by
|
|
paying the bandwidth costs incurred by your friends, who you instruct in
|
|
the use of ``--transit-helper=``.
|
|
* You publish a different application, and want to provide your users with a
|
|
relay that fails at different times than the official one
|
|
|
|
## Installation
|
|
|
|
To run a transit relay, first you need an environment to install it.
|
|
|
|
* create a virtualenv
|
|
* ``pip install magic-wormhole-transit-relay`` into this virtualenv
|
|
|
|
```
|
|
% virtualenv tr-venv
|
|
...
|
|
% tr-venv/bin/pip install magic-wormhole-transit-relay
|
|
...
|
|
```
|
|
|
|
## Running
|
|
|
|
The transit relay is not a standalone program: rather it is a plugin for the
|
|
Twisted application-running tools named ``twist`` (which only runs in the
|
|
foreground) and ``twistd`` (which daemonizes). To run the relay for testing,
|
|
use something like this:
|
|
|
|
```
|
|
% tr-venv/bin/twist transitrelay [ARGS]
|
|
2017-11-09T17:07:28-0800 [-] not blurring access times
|
|
2017-11-09T17:07:28-0800 [-] Transit starting on 4001
|
|
2017-11-09T17:07:28-0800 [wormhole_transit_relay.transit_server.Transit#info] Starting factory <wormhole_transit_relay.transit_server.Transit object at 0x7f01164b4550>
|
|
...
|
|
```
|
|
|
|
The relevant arguments are:
|
|
|
|
* ``--port=``: the endpoint to listen on, like ``tcp:4001``
|
|
* ``--log-fd=``: writes JSON lines to the given file descriptor for each connection
|
|
* ``--usage-db=``: maintains a SQLite database with current and historical usage data
|
|
* ``--blur-usage=``: round logged timestamps and data sizes
|
|
|
|
When you use ``twist``, the relay runs in the foreground, so it will
|
|
generally exit as soon as the controlling terminal exits. For persistent
|
|
environments, you should daemonize the server.
|
|
|
|
## Minimizing Log Data
|
|
|
|
The server code attempts to strike a balance between minimizing data
|
|
collected about users, and recording enough information to manage the server
|
|
and monitor its operation. The standard `twistd.log` file does not record IP
|
|
addresses unless an error occurs. The optional `--log-fd=` file (and the
|
|
SQLite database generated if `--usage-db=` is enabled) record the time at
|
|
which the first side connected, the time until the second side connected, the
|
|
total transfer time, the total number of bytes transferred, and the
|
|
success/failure status (the "mood").
|
|
|
|
If `--blur-usage=` is provided, these recorded file sizes are rounded down:
|
|
sizes less than 1kB are recorded as 0, sizes up to 1MB are rounded to the
|
|
nearest kB, sizes up to 1GB are rounded to the nearest MB, and sizes above
|
|
1GB are rounded to the nearest 100MB.
|
|
|
|
The argument to `--blur-usage=` is treated as a number of seconds, and the
|
|
"first side connects" timestamp is rounded to a multiple of this. For
|
|
example, `--blur-usage=3600` means all timestamps are rounded down to the
|
|
nearest hour. The waiting time and total time deltas are recorded without
|
|
rounding.
|
|
|
|
## Daemonization
|
|
|
|
A production installation will want to daemonize the server somehow. One
|
|
option is to use ``twistd`` (the daemonizing version of ``twist``). This
|
|
takes the same plugin name and arguments as ``twist``, but forks into the
|
|
background, detaches from the controlling terminal, and writes all output
|
|
into a logfile:
|
|
|
|
```
|
|
% tr-venv/bin/twistd transitrelay [ARGS]
|
|
% cat twistd.log
|
|
2017-11-09T17:07:28-0800 [-] not blurring access times
|
|
2017-11-09T17:07:28-0800 [-] Transit starting on 4001
|
|
2017-11-09T17:07:28-0800 [wormhole_transit_relay.transit_server.Transit#info] Starting factory <wormhole_transit_relay.transit_server.Transit object at 0x7f01164b4550>
|
|
...
|
|
% cat twistd.pid; echo
|
|
18985
|
|
```
|
|
|
|
To shut down a ``twistd``-based server, you'll need to look in the
|
|
``twistd.pid`` file for the process id, and kill it:
|
|
|
|
```
|
|
% kill `cat twistd.pid`
|
|
```
|
|
|
|
To start the server each time the host reboots, you might use a crontab
|
|
"@reboot" job, or a systemd unit.
|
|
|
|
Another option is to run ``twist`` underneath a daemonization tool like
|
|
``daemontools`` or ``start-stop-daemon``. Since ``twist`` is just a regular
|
|
program, this leaves the daemonization tool in charge of issues like
|
|
restarting a process that exits unexpectedly, limiting the rate of
|
|
respawning, and switching to the correct user-id and base directory.
|
|
|
|
Packagers who create an installable transit-relay server package should
|
|
choose a suitable daemonization tool that matches the practices of the target
|
|
operating system. For example, Debian/Ubuntu packages should probably include
|
|
a systemd unit that runs ``twist transitrelay`` in some
|
|
``/var/run/magic-wormhole-transit-relay/`` directory.
|
|
|
|
Production environments that want to monitor the server for capacity
|
|
management can use the ``--log-fd=`` option to emit logs, then route those
|
|
logs into a suitable analysis tool. Other environments might be content to
|
|
use ``--usage-db=`` and run the included Munin plugins to monitor usage.
|
|
|
|
There is also a
|
|
[Dockerfile](https://github.com/ggeorgovassilis/magic-wormhole-transit-relay-docker),
|
|
written by George Georgovassilis, which you might find useful.
|
|
|
|
## Configuring Clients
|
|
|
|
The transit relay will listen on an "endpoint" (usually a TCP port, but it
|
|
could be a unix-domain socket or any other Endpoint that Twisted knows how to
|
|
listen on). By default this is ``tcp:4001``. The relay does not know what
|
|
hostname or IP address might point at it.
|
|
|
|
Clients are configured with a "Transit Helper" setting that includes both the
|
|
hostname and the port number, like the default
|
|
``tcp:transit.magic-wormhole.io:4001``. The standard ``wormhole`` tool takes
|
|
a ``--transit-helper=`` argument to override this. Other applications that
|
|
use ``wormhole`` as a library will have internal means to configure which
|
|
transit relay they use.
|
|
|
|
If you run your own transit relay, you will need to provide the new settings
|
|
to your clients for it to be used.
|
|
|
|
The standard ``wormhole`` tool is used by two sides: the sender and the
|
|
receiver. Both sides exchange their configured transit relay with their
|
|
partner. So if the sender overrides ``--transit-helper=`` but the receiver
|
|
does not, they might wind up using either relay server, depending upon which
|
|
one gets an established connection first.
|