docs/install.md

   1 Installation
   2 ============
   3
   4 Hippotat is written in Rust.
   5 The documentation is procssed with Sphinx.
   6
   7 It is most convenient to install (especailly the server) as a `.deb`.
   8
   9 Building .debs
  10 --------------
  11
  12 On a system with a new enough `cargo` and `rustc`:
  13
  14 ```
  15    apt-get build-dep .
  16    CARGO='cargo --locked' dpkg-buildpackage -uc -b
  17 ```
  18
  19 Sadly, Debian bullseye is not new enough;
  20 to build there you will need to install Rust from upstream e.g.
  21 [using Rustup](https://www.rust-lang.org/learn/get-started).
  22
  23 In any case, the build runes above will download dependencies
  24 from the upstream Rust package repository.
  25 The precise versions of those dependencies, and their precise contents,
  26 are controlled and checked
  27 by the `Cargo.lock` file shipped in the Hippotat source tree,
  28 provided that `cargo --locked` is used.
  29
  30
  31 Installation
  32 ------------
  33
  34  * On the server: `apt install hippotat-{server,common}_*.deb`
  35  * On the client: `apt install hippotat-{client,common}_*.deb`
  36
  37 This will also install the `userv` privsep tool,
  38 and the `userv-ipif` utility for unprivileged network interface management.
  39
  40
  41 Configuration
  42 -------------
  43
  44 You will need to:
  45
  46  1. Choose a suitable URL that Hippotat will be able to listen on.
  47     This should be port 80, or 443 with TLS.
  48     You can use a reverse proxy
  49     (but you may want to suppress some of the logging).
  50     If using a reverse proxy,
  51     you must choose an internal IP port for the Hippotat server to use.
  52
  53  2. Select a private network range for use by the IP-over-HTTP system,
  54     and assign addresses to the server and to each client.
  55     If you use a range from RFC1918, choose it at random,
  56     eg using the [Cambridge G-RIN](https://www.ucam.org/cam-grin/).
  57
  58  3. Configure your firewalls to restrict access from that range
  59     to internal resources
  60     (eg, which might otherwise trust Hippotat addresses due to them
  61     being in RFC1918 private use ranges).
  62     Note that
  63     **Hippotat does not provide strong authentication or confidentiality**.
  64
  65  4. Configure `authbind` to allow the service user `_hippotat`
  66     (created by the package installation)
  67     to bind to the port you have chosen,
  68     on the server.
  69
  70  5. Configure `ipif` to allow
  71     the service user `_hippotat` (on the server)
  72     or your own user (on the client)
  73     to create network interfaces
  74     using addresses in the range you have assigned.
  75
  76  6. Configure `hippotat` itself, at both ends.
  77
  78
  79 Startup - server
  80 ----------------
  81
  82 The `hippotat-server` package
  83 supplies an init script
  84 which will start the `hippotatd` server program,
  85 if `/etc/hippotat/main.cfg` exists.
  86 If you just created that file,
  87 `service hippotatd start` will start the server..
  88
  89 Consult the init script to see options you can put in
  90 `/etc/default/hippotat`.
  91
  92
  93 Usage - client
  94 --------------
  95
  96 It is not usual to have hippotat running all the time,
  97 since its approach is rather wasteful,
  98 and not needed in a sensible network environment.
  99
 100 When you find yourself in a bad network environment,
 101 run `hippotat` from a shell.
 102 It will bring up the hippotat link.
 103 When you don't need Hippotat any more, simply `^C` it.
 104
 105 With the link up you can `ssh` (or, maybe, `mosh`) to the server,
 106 using the server's Hippotat IP address.
 107 If you are using [secnet](https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/secnet.git/)'s polypath feature,
 108 secnet will automatically start to use hippotat.
 109
 110 Don't send traffic you care about unencrypted over Hippotat.
 111 Hippotat's security mechanisms are designed
 112 to try to minimise denial of service,
 113 especially by off-path entities,
 114 but **data confidentiality and integrity are not provided**.
 115
 116
 117 Troubleshooting
 118 ---------------
 119
 120 The server will log to syslog, facility `daemon`, by default.
 121
 122 The client will report its progress to stderr.