docs

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README.md b/README.md
index c516b33174ea355933b2c99e3400281e32bb3609..0e68dffef3cc6064785fb821848bb482fe1ca673 100644 (file)
--- 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 5abddf29a367f8142c154df50d6510a6885c31c5..e91ff701ba9322a07cfc6d15ea3cd4037d899b12 100644 (file)
--- 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 edc7177a6aa7f0cd12c0957fd55abec1e16f0f0f..de829c5a4c37010b71f924caab593cb405a5042a 100644 (file)
--- 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`.