ptth/README.md

165 lines
4.6 KiB
Markdown

# PTTH
An HTTP server that can run behind a firewall by connecting out to a relay.
```
Outside the tunnel
+--------+ +------------+ +-------------+
| Client | ------> | PTTH relay | <----- | PTTH server |
+--------+ +------------+ +-------------+
Inside the tunnel
+--------+ -------------- +-------------+
| Client | ----------------------------> | 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 (A Dockerfile is provided with no guarantees)
- 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)
Copyright 2020 "Trish"