1 b9220ca4 2021-01-11 op # gmid
  2 3e4749f7 2020-10-02 op 
  3 b9220ca4 2021-01-11 op > dead simple, zero configuration Gemini server
  4 3e4749f7 2020-10-02 op 
  5 881a9dd9 2021-01-16 op gmid is a simple and minimal Gemini server.  It can run without
  6 881a9dd9 2021-01-16 op configuration, so it's well suited for local development, but at the
  7 881a9dd9 2021-01-16 op same time has a configuration file flexible enough to meet the
  8 881a9dd9 2021-01-16 op requirements of most capsules.
  9 3e4749f7 2020-10-02 op 
 10 881a9dd9 2021-01-16 op gmid was initially written to serve static files, but can also
 11 881a9dd9 2021-01-16 op optionally execute CGI scripts.  It was also written with security in
 12 ea58dab1 2021-01-17 op mind: on Linux, FreeBSD and OpenBSD is sandboxed via `seccomp(2)`,
 13 ea58dab1 2021-01-17 op `capsicum(4)`and `pledge(2)`+`unveil(2)` respectively.
 14 3e4749f7 2020-10-02 op 
 15 3e4749f7 2020-10-02 op 
 16 b9220ca4 2021-01-11 op ## Features
 17 3e4749f7 2020-10-02 op 
 18 4d2ec6d7 2021-01-13 op  - IRI support (RFC3987)
 19 b9220ca4 2021-01-11 op  - dual stack: can serve over both IPv4 and IPv6
 20 b9220ca4 2021-01-11 op  - CGI scripts
 21 b9220ca4 2021-01-11 op  - (very) low memory footprint
 22 b9220ca4 2021-01-11 op  - small codebase, easily hackable
 23 b9220ca4 2021-01-11 op  - virtual hosts
 24 ea58dab1 2021-01-17 op  - sandboxed by default on OpenBSD, Linux and FreeBSD
 25 0b00962d 2021-01-25 op  - chroot support
 26 3e4749f7 2020-10-02 op 
 27 fab952e1 2020-10-03 op 
 28 b9220ca4 2021-01-11 op ## Drawbacks
 29 3e4749f7 2020-10-02 op 
 30 b9220ca4 2021-01-11 op  - not suited for very busy hosts.  If you receive an high number of
 31 b9220ca4 2021-01-11 op    connection per-second you'd probably want to run multiple gmid
 32 b9220ca4 2021-01-11 op    instances behind relayd/haproxy or a different server.
 33 85dff1f9 2021-01-11 op 
 34 b9220ca4 2021-01-11 op ## Building
 35 3e4749f7 2020-10-02 op 
 36 5f564d23 2021-01-17 op gmid depends on a POSIX libc and libtls (provided either by LibreSSL
 37 5f564d23 2021-01-17 op or libretls).  At build time, flex and yacc (or GNU bison) are also
 38 5f564d23 2021-01-17 op needed.
 39 3e4749f7 2020-10-02 op 
 40 771d8f28 2021-01-17 op The build is as simple as
 41 3e4749f7 2020-10-02 op 
 42 b9220ca4 2021-01-11 op     make
 43 3e4749f7 2020-10-02 op 
 44 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
 45 f980545b 2021-01-21 op issue or notify me via email.
 46 8f0da580 2021-01-21 op 
 47 771d8f28 2021-01-17 op To install execute:
 48 881a9dd9 2021-01-16 op 
 49 771d8f28 2021-01-17 op     make install
 50 771d8f28 2021-01-17 op 
 51 17b09e3c 2021-01-18 op If you have trouble installing LibreSSL or libretls, as they aren't
 52 17b09e3c 2021-01-18 op available as package on various Linux distribution, you can use Docker
 53 17b09e3c 2021-01-18 op to build a `gmid` image with:
 54 771d8f28 2021-01-17 op 
 55 17b09e3c 2021-01-18 op     docker build -t gmid .
 56 17b09e3c 2021-01-18 op 
 57 17b09e3c 2021-01-18 op and then run it with something along the lines of
 58 17b09e3c 2021-01-18 op 
 59 17b09e3c 2021-01-18 op     docker run --rm -it -p 1965:1965 \
 60 17b09e3c 2021-01-18 op         -v /path/to/cert.pem:...:ro \
 61 17b09e3c 2021-01-18 op         -v /path/to/key.pem:...:ro \
 62 17b09e3c 2021-01-18 op         -v /path/to/docs:/var/gemini \
 63 17b09e3c 2021-01-18 op         gmid -f -d /var/gemini -K ... -C ...
 64 17b09e3c 2021-01-18 op 
 65 17b09e3c 2021-01-18 op ellipses used for brevity.
 66 17b09e3c 2021-01-18 op 
 67 dd8cc7d3 2021-01-22 op ### Local libretls
 68 17b09e3c 2021-01-18 op 
 69 8f0da580 2021-01-21 op This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
 70 8f0da580 2021-01-21 op your distribution of choice or use docker instead.
 71 8f0da580 2021-01-21 op 
 72 8f0da580 2021-01-21 op However, it's possible to link `gmid` to locally-installed libtls
 73 8f0da580 2021-01-21 op quite easily.  (It's how I test gmid on Fedora, for instance)
 74 8f0da580 2021-01-21 op 
 75 04397b32 2021-01-21 op Let's say you have compiled and installed libretls in `$LIBRETLS`,
 76 8f0da580 2021-01-21 op then you can build `gmid` with
 77 8f0da580 2021-01-21 op 
 78 04397b32 2021-01-21 op     ./configure CFLAGS="-I$LIBRETLS/include" \
 79 45b4aa6e 2021-01-23 op                 LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread"
 80 8f0da580 2021-01-21 op     make
 81 8f0da580 2021-01-21 op 
 82 dd8cc7d3 2021-01-22 op ### Testing
 83 dd8cc7d3 2021-01-22 op 
 84 31a4993a 2021-01-23 op Execute
 85 dd8cc7d3 2021-01-22 op 
 86 dd8cc7d3 2021-01-22 op     make regress
 87 dd8cc7d3 2021-01-22 op 
 88 7f740a14 2021-01-22 op to start the suite.  Keep in mind that the suite will create files
 89 dd8cc7d3 2021-01-22 op inside the `regress` directory and bind the 10965 port.
 90 dd8cc7d3 2021-01-22 op 
 91 dd8cc7d3 2021-01-22 op 
 92 881a9dd9 2021-01-16 op ## Architecture/Security considerations
 93 881a9dd9 2021-01-16 op 
 94 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor.  The
 95 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
 96 881a9dd9 2021-01-16 op sandboxed.  When a CGI script needs to be executed, the executor
 97 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
 98 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
 99 881a9dd9 2021-01-16 op This way, is still possible to execute CGI scripts without restriction
100 15209ad9 2021-01-21 op even in the presence of a sandbox.
101 881a9dd9 2021-01-16 op 
102 881a9dd9 2021-01-16 op On OpenBSD, the listener process runs with the `stdio recvfd rpath
103 881a9dd9 2021-01-16 op inet` pledges and has `unveil(2)`ed only the directories that it
104 ea58dab1 2021-01-17 op serves; the executor has `stdio sendfd proc exec` as pledges.
105 881a9dd9 2021-01-16 op 
106 ea58dab1 2021-01-17 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
107 d939d0f0 2021-01-17 op 
108 76fd55f4 2021-01-17 op On Linux, a `seccomp(2)` filter is installed to allow only certain
109 76fd55f4 2021-01-17 op syscalls, see [sandbox.c](sandbox.c) for more information on the BPF
110 ea58dab1 2021-01-17 op program.
111 ea58dab1 2021-01-17 op 
112 ea58dab1 2021-01-17 op In any case, you are invited to run gmid inside some sort of
113 0b00962d 2021-01-25 op container/jail/chroot.