165 lines
4.6 KiB
Markdown
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"
|