docs/install.md

   1 Installation and requirements
   2 ==============================
   3
   4 Hippotat is written in Rust.
   5 The documentation is procssed with Sphinx.
   6
   7 It is must 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 Installing
  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 install the `userv` privsep tool,
  38 and the `userv-ipif` utility for unprivileged network interface management.
  39
  40
  41 System 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
  56  3. Configure your firewall to restrict access from that range
  57     to internal resources
  58     (eg, which might otherwise trust Hippotat addresses due to them
  59     being in RFC1918 private use ranges).
  60     Note that Hippotat
  61     **does not provide strong authentication or confidentiality**.
  62
  63  4. Configure `authbind` to allow the service user `_hippotat`
  64     (created by the package installation)
  65     to bind to the port you have chosen.
  66
  67  5. Configure `ipif` to allow the service user `_hippotat`
  68     to create network interfaces
  69     using addresses in the range you have assigned.
  70
  71  6. Configure `hippotat` itself, at both ends.
  72
  73
  74 Startup - server
  75 ----------------
  76
  77 The `hippotat-server` package
  78 will start the `hippotatd` server program,
  79 if `/etc/hippotat/main.cfg` exists.
  80
  81 Consult the init script to see options you can put in
  82 `/etc/default/hippotat`.
  83
  84
  85 Usage - client
  86 --------------
  87
  88 It is not usual to have hippotat running all the time,
  89 since its approach is rather wasteful,
  90 and not needed in a sensible network environment.
  91
  92 When you find yourself in a bad network environment,
  93 run `hippotat` from a shell.
  94 It will bring up the hippotat link.
  95
  96 With the link up you can `ssh` (or, maybe, `mosh`) to the server,
  97 using the server's Hippotat IP address.
  98 If you are using [secnet]'s polypath feature,
  99 secnet will automatically start to use hippotat.