README.md

   1 # Diohsc: Denotationally Intricate Obedient Haskell Smallnet Client
   2 diohsc [URI]
   3
   4 ## Features
   5 * Simple line-based command-response terminal user interface with ANSI colour.
   6 * Terse but combinatorially expressive command language.
   7 * Navigational aids: history, marks, queue.
   8 * Facilities to invoke external commands and use per-scheme proxies.
   9 * Responses streamed to pager or external command.
  10 * Certificate checking with TOFU and/or explicitly trusted CAs.
  11 * Support for TLS resuming, 0RTT, and client certificates.
  12 * All configuration and certificates stored as user-manipulable files.
  13 * Extensive help.
  14
  15 ## Building
  16 Install the haskell package manager cabal; e.g. on a debian system:
  17 ```
  18 $ sudo apt-get install cabal-install
  19 ```
  20 Then in the diohsc directory, run
  21 ```
  22 $ cabal update && cabal install
  23 ```
  24 The resulting binary will be installed as `~/.cabal/bin/diohsc`.
  25
  26 ### Compile-time options
  27 * `cabal install -f magic`: use libmagic to detect mimetypes of local files
  28 * `cabal install -f irilinks`: allow IRIs in gemtext links
  29
  30 ## Trusting server certificates
  31 Diohsc uses "Trust On First Use": if a host provides a certificate chain you do not currently trust, the client will ask for confirmation then add the certificate for the host to a collection stored in `~/.diohsc/known_hosts/` if there isn't already one stored; if there is one already stored, it will give some details and ask if you want to overwrite it with the newly provided one.
  32
  33 You can also trust Certificate Authorities by putting their certificates in `~/.diohsc/trusted_certs/`. For example, if you want to trust all the certificates installed on your system,
  34 ```
  35 $ ln -s /etc/ssl/certs/* ~/.diohsc/trusted_certs/
  36 ```
  37 or if you just want to trust Let's Encrypt:
  38 ```
  39 $ mkdir ~/.diohsc/trusted_certs
  40 $ wget -O ~/.diohsc/trusted_certs/lets-encrypt-x3-cross-signed.pem https://letsencrypt.org/certs/lets-encrypt-x3-cross-signed.pem
  41 $ sha256sum ~/.diohsc/trusted_certs/lets-encrypt-x3-cross-signed.pem
  42 e446c5e9dbef9d09ac9f7027c034602492437a05ff6c40011d7235fca639c79a /home/me/.diohsc/trusted_certs/lets-encrypt-x3-cross-signed.pem
  43 ```
  44
  45 ## Configuration
  46 See diohscrc.sample for ideas for configuration options, in particular indicating how to make use of third-party software to allow diohsc to access gopher and the web, parse markdown and html, and provide ascii-art previews of image files. Copy the file to ~/.diohsc/diohscrc and uncomment lines as appropriate.
  47
  48 ## Multiple instances
  49 Multiple simultaneous diohsc instances may share ~/.diohsc without serious conflict. However, command history is written only on exit, so the last instance to exit will determine that history. The log is appended to continuously, but read only on startup, so logs from simultaneous instances will be interleaved. Uris in ~/.diohsc/queue are taken by an instance on startup and whenever it processes a command, and leftover queue items are written there on exit.
  50
  51 To ensure that an instance won't interfere with other running instances: either use "--datadir" to specify an alternative directory to ~/.diohsc, or use the "--ghost" option (which also acts as a "private browsing" mode).
  52
  53 ## Running under Windows
  54 It is apparently possible to compile and run diohsc on Windows. However, it requires a terminal with ANSI and unicode support, which it seems is not the default situation in even the most recent versions of Windows. On Windows 10, following the instructions of this link has been reported to work:
  55 [https://akr.am/blog/posts/using-utf-8-in-the-windows-terminal](https://akr.am/blog/posts/using-utf-8-in-the-windows-terminal)