diff --git a/README-safe.md b/README-safe.md new file mode 100644 index 0000000..d0eec8c --- /dev/null +++ b/README-safe.md @@ -0,0 +1,159 @@ +# PTTH + +An HTTP server that can run behind a firewall by connecting out to a relay. + +``` ++--------+ +------------+ +-------------+ +| Client |-------->| PTTH relay |<-------| PTTH server | ++--------+ +------------+ +-------------+ +``` + +The server can run behind a firewall, because it is actually a special HTTP +client. + +## How to configure + +The server must be configured first so that its tripcode can be registered +with the relay. + +Configuring a server: + +- Copy ptth_server or ptth_server.exe onto the server +- Create ptth_server.toml in the server's working dir +- Add a human-readable name and a secret API key generated by diceware method +- Run the server and use Ctrl+C to close it. It will print a tripcode to +the terminal. Copy that to the relay. + +Configuring the relay: + +- Copy ptth_relay onto the server +- Create ptth_relay.toml in the relay's working dir +- Add the tripcodes of all servers to the server_tripcodes table + +Example server config: (Won't run because the key is too weak) + +``` +name = "my_server" +api_key = "secretpassword" +relay_url = "http://127.0.0.1:4000" +``` + +Example relay config: + +``` +[server_tripcodes] + +my_server = "czpCob1t1T7IU9zIlYyoNRomyeN7pqKSg1R0EUPz6Pw=" +some_other_server = "su2wWbTyf5xih4yiCTfAzqDlASatV+0dI+UVKFBIsEI=" +``` + +## How to run + +The relay should run first so that the server(s) can connect to it without error. + +1. Start the relay +2. Start a server +3. Use a client to access a server through the relay + +From the source code directory: + +- `cargo run --bin ptth_relay` +- `cargo run --bin ptth_server` +- `firefox http://127.0.0.1:4000/servers/my_server/files/` + +If you only have pre-built binaries: + +- `./ptth_relay` +- `./ptth_server` +- `firefox http://127.0.0.1:4000/servers/my_server/files/` + +"ptth_file_server" is not needed for production. It's a standalone build of +the file server module, for testing. + +## Comparison with normal HTTP + +Normal HTTP: + +``` +Client Server + + H1 + O ---------> O + | H2 + O <--------- O + H3 +``` + +1. The client connects to the server and sends a request +2. The server accepts the connection and processes the request +3. The server responds with a response + +We'll call these steps "H1", "H2", and "H3" in the next section. + +PTTH: + +``` +Client Relay Server + + P1 + O <----- O + P2/H1 | + O ------> O + | P3 + O -----> O + | P4/H2 + O <----- O + | P5 + O <------ O + P6/H3 +``` + +We'll call these steps "P1" through "P6". + +1. The server makes a "listen" request to the relay, +punching out through the server's firewall. +The server and relay are now in a long-polling state with each other, +waiting for a client to make a request. +2. A client makes a request to the relay. (P2 == H1) +3. The relay packages the request and sends it as a response to the server, +completing the server's request in P1. +The client and relay are now in a long-polling state, waiting for the server +to respond. +4. The server processes the request. (P4 == H2) +5. The server packages its response in another request to the relay. +6. The relay unwraps the request and forwards it to the client. (P6 == H3) + +Every step of the normal HTTP process is inverted for the server: + +- It must stay connected to the relay even when nothing is happening +- A request arrives packaged in a response +- A response is sent out packaged as a request + +There are twice as many steps, and the per-connection and per-request overhead +is probably high. But once the connections are established, the only +overhead is that of using a relay, which is similar to many other file transfer +or remote desktop software. + +## Comparison with similar software + +PTTH is very similar to [PageKite](https://github.com/pagekite/PyPagekite). +PTTH's relay is equivalent to PageKite's front-end server, and PTTH's server +is equivalent to (I think) PageKite's backend. + +WireGuard can also pierce firewalls, but it requires root permissions, +and the client must be a WireGuard node. PTTH allows any normal HTTP client +such as curl, Firefox, etc. + +## Why are GitHub issues disabled? + +Because they are not part of Git. + +For now, either email me (if you know me personally) or make a pull request to add an item to todo.md. + +## License + +PTTH is licensed under the +[GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.html), +with an exception for my current employer. + +Copyright 2020 "Trish"