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 For complete documentation, please see https://magic-wormhole.readthedocs.io
or the docs/ subdirectory. 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 ## License, Compatibility
Magic-Wormhole is released under the MIT license, see the `LICENSE` file for details. 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 ## Relays
The wormhole library requires a "Rendezvous Server": a simple WebSocket-based The wormhole library requires a "Mailbox Server" (also known as the
relay that delivers messages from one client to another. This allows the "Rendezvous Server"): a simple WebSocket-based relay that delivers messages
wormhole codes to omit IP addresses and port numbers. The URL of a public from one client to another. This allows the wormhole codes to omit IP
server is baked into the library for use as a default, and will be freely addresses and port numbers. The URL of a public server is baked into the
available until volume or abuse makes it infeasible to support. Applications library for use as a default, and will be freely available until volume or
which desire more reliability can easily run their own relay and configure abuse makes it infeasible to support. Applications which desire more
their clients to use it instead. Code for the Rendezvous Server is included reliability can easily run their own relay and configure their clients to use
in the library. 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 The file-transfer commands also use a "Transit Relay", which is another
simple server that glues together two inbound TCP connections and transfers 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 data on each to the other (the moral equivalent of a TURN server). The
addresses of each client with the other (inside the encrypted message), and `wormhole send` file mode shares the IP addresses of each client with the
both clients first attempt to connect directly. If this fails, they fall back other (inside the encrypted message), and both clients first attempt to
to using the transit relay. As before, the host/port of a public server is connect directly. If this fails, they fall back to using the transit relay.
baked into the library, and should be sufficient to handle moderate traffic. As before, the host/port of a public server is baked into the library, and
Code for the Transit Relay is provided a separate package named should be sufficient to handle moderate traffic. Code for the Transit Relay
`magic-wormhole-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 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 clients: if either relay must be shut down, these channels will be used to