From d7a34f2a7ddce937b77220c5f725ff114661a3fd Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 27 Sep 2022 22:39:52 +0100 Subject: [PATCH] docs: install docs wip Signed-off-by: Ian Jackson --- docs/index.rst | 1 + docs/install.md | 48 ++++++++++++++++++++++++++++++++++-------------- 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 0925038..5abddf2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Hippotat - Asinine IP over HTTP :caption: Contents: README + install.md config.md settings.md diff --git a/docs/install.md b/docs/install.md index 9b3a540..0c7e07c 100644 --- 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. -- 2.30.2