open.source/magic-wormhole
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add pointers to server code and setup instructions

Browse Source 
Thanks to @kaie for the suggestion.

Closes #387
This commit is contained in:
Brian Warner 2020-05-21 21:11:40 -07:00
parent aa555a82ed
commit 95a628e1a7
2 changed files with 31 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -24,6 +24,12 @@ and do not need to be memorized.
For complete documentation, please see https://magic-wormhole.readthedocs.io
or the docs/ subdirectory.
This program uses two servers, whose source code is kept in separate
repositories: the
[mailbox server](https://github.com/warner/magic-wormhole-mailbox-server),
and the
[transit relay](https://github.com/warner/magic-wormhole-transit-relay).
## License, Compatibility
Magic-Wormhole is released under the MIT license, see the `LICENSE` file for details.

40
docs/welcome.md
View File

@ -197,24 +197,34 @@ running until the transfer has finished.
## Relays
The wormhole library requires a "Rendezvous Server": a simple WebSocket-based
relay that delivers messages from one client to another. This allows the
wormhole codes to omit IP addresses and port numbers. The URL of a public
server is baked into the library for use as a default, and will be freely
available until volume or abuse makes it infeasible to support. Applications
which desire more reliability can easily run their own relay and configure
their clients to use it instead. Code for the Rendezvous Server is included
in the library.
The wormhole library requires a "Mailbox Server" (also known as the
"Rendezvous Server"): a simple WebSocket-based relay that delivers messages
from one client to another. This allows the wormhole codes to omit IP
addresses and port numbers. The URL of a public server is baked into the
library for use as a default, and will be freely available until volume or
abuse makes it infeasible to support. Applications which desire more
reliability can easily run their own relay and configure their clients to use
it instead. Code for the Mailbox Server is in a separate package named
`magic-wormhole-mailbox-server`. and
https://github.com/warner/magic-wormhole-mailbox-server/blob/master/docs/welcome.md
has instructions to run your own copy. Both clients must use the same mailbox
server. The default can be overridden with the `--relay-url` option.
The file-transfer commands also use a "Transit Relay", which is another
simple server that glues together two inbound TCP connections and transfers
data on each to the other. The `wormhole send` file mode shares the IP
addresses of each client with the other (inside the encrypted message), and
both clients first attempt to connect directly. If this fails, they fall back
to using the transit relay. As before, the host/port of a public server is
baked into the library, and should be sufficient to handle moderate traffic.
Code for the Transit Relay is provided a separate package named
`magic-wormhole-transit-relay`.
data on each to the other (the moral equivalent of a TURN server). The
`wormhole send` file mode shares the IP addresses of each client with the
other (inside the encrypted message), and both clients first attempt to
connect directly. If this fails, they fall back to using the transit relay.
As before, the host/port of a public server is baked into the library, and
should be sufficient to handle moderate traffic. Code for the Transit Relay
is provided a separate package named `magic-wormhole-transit-relay`, and you
can read
https://github.com/warner/magic-wormhole-transit-relay/blob/master/docs/running.md
for instructions on running your own. The clients exchange transit relay
information during connection negotiation, so they can be configured to use
different ones without problems. Use the `--transit-helper` option to
override the default.
The protocol includes provisions to deliver notices and error messages to
clients: if either relay must be shut down, these channels will be used to