From 75a55a80d752b8f5920da773c574f92320d89c76 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Wed, 28 Sep 2022 19:22:33 +0100 Subject: [PATCH] docs Signed-off-by: Ian Jackson --- README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++-- docs/index.rst | 2 +- docs/install.md | 7 ++++-- 3 files changed, 66 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c516b33..0e68dff 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,60 @@ -Introduction -============ +Hippotat - asinine IP over HTTP +=============================== + +Hippotat is a system to allow you to use your normal VPN, +ssh, and other applications, even in broken network environments +that are only ever tested with "web stuff". + +Packets are parcelled up into HTTP POST requests, resembling +form submissions (or JavaScript XMLHttpRequest traffic), +and the returned packets arrive via the HTTP response bodies. + +Scenario +-------- + +You're in a cafe or a hotel, trying to use the provided wifi. +But it's not working. You discover that port 80 and port 443 +are open, but the wifi forbids all other traffic. + +Never mind, start up your hippotat client. Now you have connectivity. +Your VPN and SSH and so on run over Hippotat. +The result is not very efficient, but it does work. + +The design goal is that if the your barista's phone works OK, +or the hotel concierge can see Google on their computer, +you can use the internet properly, despite +whatever breakage and nonsense. + +So Hippotat is an alternative to the futile strategy of +trying to report technical bugs, or stupid portblocks, +in terrible wifi systems. + +Of course it can't always help. +If the wifi is bad enough that one's hosts' +devices don't work reliably either, +hopefully you can probably get them to reboot the magic box, +or maybe get some money off, if wifi was supposed to be included. + +Non-goals +--------- + +**Hippotat does not provide meaningful encryption**. +You should use protocols over the top of it +that you would be happy to run over the public internet: +encrypted ones, like a VPN or SSH. + +Use of Hippotat is not intended to be undetectable, +or even particularly hard to distinguish from other uses of HTTP, +should someone want to go to the effort. +Rather, it is intended to be deployed against idiocy, ignorance, +and incompetence. + +Protection against interference is limited to +trying to defend against off-path attackers, and +arranging that formerly-on-path attackers' +ability to do harm will expire reasonably soon. + +Hippotat is not designed to allow you to "leech" internet access +from "closed" Wifi. +It won't work if "normal web access" doesn't. +You might try IP-over-DNS systems for that. diff --git a/docs/index.rst b/docs/index.rst index 5abddf2..e91ff70 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,7 @@ Hippotat - Asinine IP over HTTP :maxdepth: 2 :caption: Contents: - README + README.md install.md config.md settings.md diff --git a/docs/install.md b/docs/install.md index edc7177..de829c5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -52,6 +52,8 @@ You will need to: 2. Select a private network range for use by the IP-over-HTTP system, and assign addresses to the server and to each client. + If you use a range from RFC1918, choose it at random, + eg using the [Cambridge G-RIN](https://www.ucam.org/cam-grin/). 3. Configure your firewalls to restrict access from that range to internal resources @@ -79,9 +81,10 @@ Startup - server The `hippotat-server` package supplies an init script -will start the `hippotatd` server program, +which will start the `hippotatd` server program, if `/etc/hippotat/main.cfg` exists. -If you just configured it, `service hippotatd start` will start it. +If you just created that file, +`service hippotatd start` will start the server.. Consult the init script to see options you can put in `/etc/default/hippotat`. -- 2.30.2