Magic Wormhole - ArchWiki

Jump to content

# Magic Wormhole

From ArchWiki

This article or section needs expansion.

Reason: This page needs more details about possible configuration and usage instructions. (Discuss in Talk:Magic Wormhole)

Magic Wormhole is a peer-to-peer file transfer protocol. It uses a short code to establish a direct connection between two devices to securely transfer files.

To send a file using the `wormhole` CLI:

1. `wormhole send filename`
2. Get the code (something like 8-pharmacy-indoors) to the other device (which also must have a magic wormhole client installed):
   - Scan the QR via the relevant app, or
   - Type the code into an app, or
   - Run `wormhole receive 8-pharmacy-indoors` (replace with your actual code)

You can easily communicate the code by voice or any other secure channel, since it's short - always a number and two words. It is easy to copy-paste, since double click selects it in some/most shells as it's separated by dashes.

The protocol guarantees that unless an attacker can intercept the code you share, they cannot intercept the file you share (unless they get an unreasonably lucky guess; a failed guess cancels the send, so attacks would be very visible and very low odds to succeed).

Also useful for sending ssh public keys via `wormhole ssh invite` from the server then `wormhole ssh accept ...` on the system which would like to send a key. `wormhole ssh accept ...` requires selecting the public key to send if there is more than one.

## Install

Install magic-wormhole for the CLI.

It is more convenient to use the default servers, and the protocol provides security guarantees independent of the servers used, so the overwhelming majority of users should reasonably prefer to not run their own infrastructure. However, you can run your own if for example you are developing your own app based on the service, or wish to dedicate bandwidth to the public. To do so, install python-magic-wormhole-mailbox-server and/or python-magic-wormhole-transit-relay.

## Relay configuration

Create and enable/start the following systemd units.

    /etc/systemd/system/wormhole-mailbox.service

    [Unit]
    Description=Magic Wormhole Mailbox Server
    After=network.target

    [Service]
    ExecStart=/usr/bin/twist --log-format=text wormhole-mailbox --channel-db=/var/lib/magic-wormhole-mailbox-server/relay.sqlite
    DynamicUser=yes
    StateDirectory=magic-wormhole-mailbox-server
    RestrictNamespaces=yes
    SystemCallFilter=@system-service
    Restart=on-failure
    RestartSec=5s

    [Install]
    WantedBy=multi-user.target

    /etc/systemd/system/wormhole-relay.service

    [Unit]
    Description=Magic Wormhole Transit Relay
    After=network.target

    [Service]
    ExecStart=/usr/bin/twist --log-format=text transitrelay
    DynamicUser=yes
    RestrictNamespaces=yes
    SystemCallFilter=@system-service
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target

Using your relay depends on the client - for the refrence `wormhole` CLI client: `wormhole --relay-url=ws://server:4000/v1 --transit-helper tcp:server:4001 send file` - replace the ports if you use non-default ports. Alternatively, export the `WORMHOLE_RELAY_URL` and `WORMHOLE_TRANSIT_HELPER` environment variables, set to equivalent values.

Category:

- Peer-to-peer

Hidden category:

- Pages or sections flagged with Template:Expansion

Magic Wormhole
Add topic