Skip to main content

Securely transfer data between computers

Project description

Magic Wormhole Mailbox Server

PyPI Tests codecov.io

This repository holds the code for the main server that Magic-Wormhole clients connect to. The server performs store-and-forward delivery for small key-exchange and control messages. Bulk data is sent over a direct TCP connection, or through a transit-relay.

Clients connect with WebSockets, for low-latency delivery in the happy case where both clients are attached at the same time. Message are stored to enable non-simultaneous clients to make forward progress. The server uses a small SQLite database for persistence (and clients will reconnect automatically, allowing the server to be rebooted without losing state). An optional "usage DB" tracks historical activity for status monitoring and operational maintenance.

Installation

pip install magic-wormhole-mailbox-server

You either want to do this into a "user" environment (putting the twist and twistd executables in ~/.local/bin/) like this:

pip install --user magic-wormhole-mailbox-server

or put it into a virtualenv, to avoid modifying the system python's libraries, like this:

virtualenv venv
source venv/bin/activate
pip install magic-wormhole-mailbox-server

You probably don't want to use sudo when you run pip, since the dependencies that get installed may conflict with other python programs on your computer. pipsi is usually a good way to install into isolated environments, but unfortunately it doesn't work for magic-wormhole-mailbox-server, because we don't have a dedicated command to start the server (twist, described below, comes from the twisted package, and pipsi doesn't expose executables from dependencies).

For the installation from source, clone this repo, cd into the folder, create and activate a virtualenv, and run pip install ..

Running A Server

Note that the standard Magic-Wormhole command-line tool is preconfigured to use a mailbox server hosted by the project, so running your own server is only necessary for custom applications that use magic-wormhole as a library.

The mailbox server is deployed as a twist/twistd plugin. Running a basic server looks like this:

twist wormhole-mailbox --usage-db=usage.sqlite

Use twist wormhole-mailbox --help for more details.

If you use the default --port=tcp:4000, on a machine named example.com, then clients can reach your server with the following option:

wormhole --relay-url=ws://example.com:4000/v1 send FILENAME

Using Docker

Dockerfile content:

FROM python:3.8
RUN pip install magic-wormhole-mailbox-server
CMD [ "twist", "wormhole-mailbox","--usage-db=usage.sqlite" ] 

Note: This will be running as root, you should adjust it to be in user space for production.

Build and run:

docker build -t magicwormhole Dockerfile
docker run -p 4000:4000 -d magicwormhole

Connect:

wormhole --relay-url=ws://localhost:4000/v1 send FILENAME

License, Compatibility

This library is released under the MIT license, see LICENSE for details.

This library is compatible with python2.7, and python3 (3.5 and higher).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

magic-wormhole-mailbox-server-0.5.1.tar.gz (69.8 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file magic-wormhole-mailbox-server-0.5.1.tar.gz.

File metadata

File hashes

Hashes for magic-wormhole-mailbox-server-0.5.1.tar.gz
Algorithm Hash digest
SHA256 a007a03672293204657681dbf502045d6d5817c57f9aae2f2226e6ea1a008ca1
MD5 bb9f84e7ecddc43413b4287b7b20d285
BLAKE2b-256 9d5c71566147af3f28017035ebe69ce7253ea26917225ae7c39b964578541bff

See more details on using hashes here.

Provenance

File details

Details for the file magic_wormhole_mailbox_server-0.5.1-py3-none-any.whl.

File metadata

File hashes

Hashes for magic_wormhole_mailbox_server-0.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 7ec83164aa5269883c66522950dbf5e26214695b447f60b1ee0acacc31f8eb74
MD5 9c82c6087c242bc060e2f13201376a5e
BLAKE2b-256 a3ec096238f31f8cc198f8a8f953b6c57aea738764e47ce5c41438e8a4f978f6

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page