docs: install docs wip

[hippotat.git] / docs / install.md

diff --git a/docs/install.md b/docs/install.md
index 9b3a5403d494c99cc0e3c4eaa26ed120d582f96f..0c7e07cb6e62f82afc0f1a26768619801c81207d 100644 (file)
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,10 +1,10 @@
-Installation and requirements
-==============================
+Installation
+============
 
 Hippotat is written in Rust.
 The documentation is procssed with Sphinx.
 
-It is must convenient to install (especailly the server) as a `.deb`.
+It is most convenient to install (especailly the server) as a `.deb`.
 
 Building .debs
 --------------
@@ -28,18 +28,18 @@ by the `Cargo.lock` file shipped in the Hippotat source tree,
 provided that `cargo --locked` is used.
 
 
-Installing
-----------
+Installation
+------------
 
  * 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,
+This will also install the `userv` privsep tool,
 and the `userv-ipif` utility for unprivileged network interface management.
 
 
-System configuration
----------------------
+Configuration
+-------------
 
 You will need to:
 
@@ -53,18 +53,21 @@ 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.
 
- 3. Configure your firewall to restrict access from that range
+ 3. Configure your firewalls 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**.
+    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.
+    to bind to the port you have chosen,
+    on the server.
 
- 5. Configure `ipif` to allow the service user `_hippotat`
+ 5. Configure `ipif` to allow
+    the service user `_hippotat` (on the server)
+    or your own user (on the client)
     to create network interfaces
     using addresses in the range you have assigned.
 
@@ -75,8 +78,10 @@ Startup - server
 ----------------
 
 The `hippotat-server` package
+supplies an init script
 will start the `hippotatd` server program,
 if `/etc/hippotat/main.cfg` exists.
+If you just configured it, `service hippotatd start` will start it.
 
 Consult the init script to see options you can put in
 `/etc/default/hippotat`.
@@ -92,8 +97,23 @@ 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.
+When you don't need Hippotat any more, simply `^C` it.
 
 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,
+If you are using [secnet](https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/secnet.git/)'s polypath feature,
 secnet will automatically start to use hippotat.
+
+Don't send traffic you care about unencrypted over Hippotat.
+Hippotat's security mechanisms are designed
+to try to minimise denial of service,
+especially by off-path entities,
+but **data confidentiality and integrity are not provided**.
+
+
+Troubleshooting
+---------------
+
+The server will log to syslog, facility `daemon`, by default.
+
+The client will report its progress to stderr.