docs: install docs wip

The rune here built a thing.

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

diff --git a/docs/install.md b/docs/install.md
new file mode 100644 (file)
index 0000000..9b3a540
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,99 @@
+Installation and requirements
+==============================
+
+Hippotat is written in Rust.
+The documentation is procssed with Sphinx.
+
+It is must convenient to install (especailly the server) as a `.deb`.
+
+Building .debs
+--------------
+
+On a system with a new enough `cargo` and `rustc`:
+
+```
+   apt-get build-dep .
+   CARGO='cargo --locked' dpkg-buildpackage -uc -b
+```
+
+Sadly, Debian bullseye is not new enough;
+to build there you will need to install Rust from upstream e.g.
+[using Rustup](https://www.rust-lang.org/learn/get-started).
+
+In any case, the build runes above will download dependencies
+from the upstream Rust package repository.
+The precise versions of those dependencies, and their precise contents,
+are controlled and checked
+by the `Cargo.lock` file shipped in the Hippotat source tree,
+provided that `cargo --locked` is used.
+
+
+Installing
+----------
+
+ * On the server: `apt install hippotat-{server,common}_*.deb`
+ * On the client: `apt install hippotat-{client,common}_*.deb`
+
+This will install the `userv` privsep tool,
+and the `userv-ipif` utility for unprivileged network interface management.
+
+
+System configuration
+---------------------
+
+You will need to:
+
+ 1. Choose a suitable URL that Hippotat will be able to listen on.
+    This should be port 80, or 443 with TLS.
+    You can use a reverse proxy,
+    (but you may want to suppress some of the logging).
+    If using a reverse proxy,
+    you must choose an internal IP port for the Hippotat server to use.
+
+ 2. Select a private network range for use by the IP-over-HTTP system,
+    and assign addresses to the server and to each client.
+
+ 3. Configure your firewall to restrict access from that range
+    to internal resources
+    (eg, which might otherwise trust Hippotat addresses due to them
+    being in RFC1918 private use ranges).
+    Note that Hippotat
+    **does not provide strong authentication or confidentiality**.
+
+ 4. Configure `authbind` to allow the service user `_hippotat`
+    (created by the package installation)
+    to bind to the port you have chosen.
+
+ 5. Configure `ipif` to allow the service user `_hippotat`
+    to create network interfaces
+    using addresses in the range you have assigned.
+
+ 6. Configure `hippotat` itself, at both ends.
+
+
+Startup - server
+----------------
+
+The `hippotat-server` package
+will start the `hippotatd` server program,
+if `/etc/hippotat/main.cfg` exists.
+
+Consult the init script to see options you can put in
+`/etc/default/hippotat`.
+
+
+Usage - client
+--------------
+
+It is not usual to have hippotat running all the time,
+since its approach is rather wasteful,
+and not needed in a sensible network environment.
+
+When you find yourself in a bad network environment,
+run `hippotat` from a shell.
+It will bring up the hippotat link.
+
+With the link up you can `ssh` (or, maybe, `mosh`) to the server,
+using the server's Hippotat IP address.
+If you are using [secnet]'s polypath feature,
+secnet will automatically start to use hippotat.