diff --git a/README.md b/README.md index 2279a7d..ebfeec2 100644 --- a/README.md +++ b/README.md @@ -19,44 +19,46 @@ client. ## Glossary -- "Tunnel" - The reverse HTTP tunnel between ptth_relay and ptth_server. -ptth_server connects out to ptth_relay, then ptth_relay forwards incoming -connections to ptth_server through the tunnel. -- "Relay" or "Relay server" - The ptth_relay app. This must run on a server -that can accept incoming HTTP connections. -- "Server" or "destination server" - The ptth_server app. This should run behind -a firewall. It will connect out to the relay and accept incoming connections -through the PTTH tunnel. -- "Client" - Any client that connects to the relay in order to reach a +(sorted alphabetically) + +- **Backend API** - The HTTP API that ptth_server uses to establish the tunnel. +Noted in the code with the cookie "7ZSFUKGV". +- **Client** - Any client that connects to ptth_relay in order to reach a destination server. Admins must terminate TLS between ptth_relay and all clients. -- "Frontend" - The human-friendly HTTP+HTML interface that ptth_relay either -serves directly or relays from ptth_server. This interface has no auth by -default. Admins must provide their own auth in front of ptth_relay. -OAuth2 is recommended. -- "Backend API" - The HTTP API that ptth_server uses to establish the tunnel. -Noted in the code with the cookie "7ZSFUKGV". -- "Scraper API" - An optional HTTP API for scraper clients to access ptth_relay and +- **Frontend** - The human-friendly, browser-friendly HTTP+HTML interface +that ptth_relay serves directly or relays from ptth_server. +This interface has no auth by default. Admins must provide their own auth +in front of ptth_relay. OAuth2 is recommended. +- **ptth_file_server** - A standalone file server. It uses the same code +as ptth_server, so production environments don't need it. +- **ptth_relay** or **Relay server** - The ptth_relay app. This must run on a server +that can accept incoming HTTP connections. +- **ptth_server** or **Destination server** - The ptth_server app. This should run behind +a firewall. It will connect out to the relay and accept incoming connections +through the PTTH tunnel. +- **Scraper API** - An optional HTTP API for scraper clients to access ptth_relay and the destination servers using machine-friendly auth. +- **Tripcode** - The base64 hash of a server's private API key. When adding +a new server, the tripcode must be copied to ptth_relay.toml on the relay +server. +- **Tunnel** - The reverse HTTP tunnel between ptth_relay and ptth_server. +ptth_server connects out to ptth_relay, then ptth_relay forwards incoming +connections to ptth_server through the tunnel. -## How to configure +## Configuration -The server must be configured first so that its tripcode can be registered -with the relay. - -Configuring a server: +ptth_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. +- Add a human-readable name and a secret API key generated by diceware +- Run `ptth_server --print-tripcode` and copy the output into ptth_relay.toml -Configuring the relay: +ptth_relay first-time config: - 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) @@ -64,20 +66,22 @@ 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" +file_server_root = "./data" ``` -Example relay config: +ptth_relay.toml: ``` -[server_tripcodes] +[[servers]] +name = "my_server" +tripcode = "czpCob1t1T7IU9zIlYyoNRomyeN7pqKSg1R0EUPz6Pw=" -my_server = "czpCob1t1T7IU9zIlYyoNRomyeN7pqKSg1R0EUPz6Pw=" -some_other_server = "su2wWbTyf5xih4yiCTfAzqDlASatV+0dI+UVKFBIsEI=" +[[servers] +name = "some_other_server" +tripcode = "su2wWbTyf5xih4yiCTfAzqDlASatV+0dI+UVKFBIsEI=" ``` -## How to run - -The relay should run first so that the server(s) can connect to it without error. +## Use 1. Start the relay 2. Start a server @@ -95,9 +99,6 @@ If you only have pre-built binaries: - `./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. - To run the relay behind Nginx, these directives improve time-to-first-byte when streaming: