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 2f09adb0 2021-01-25 op It 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 2f09adb0 2021-01-25 op gmid can be used from the command line to serve local directories
 16 3e4749f7 2020-10-02 op 
 17 2f09adb0 2021-01-25 op     # serve the directory docs
 18 2f09adb0 2021-01-25 op     gmid docs
 19 2f09adb0 2021-01-25 op 
 20 0a0e6ba7 2021-01-25 op or you can pass a configuration file and have access to all the
 21 0a0e6ba7 2021-01-25 op features
 22 2f09adb0 2021-01-25 op 
 23 2f09adb0 2021-01-25 op     gmid -c /etc/gmid.conf
 24 2f09adb0 2021-01-25 op 
 25 2f09adb0 2021-01-25 op Please consult the [manpage](gmid.1) for more information.
 26 2f09adb0 2021-01-25 op 
 27 2f09adb0 2021-01-25 op 
 28 b9220ca4 2021-01-11 op ## Features
 29 3e4749f7 2020-10-02 op 
 30 4d2ec6d7 2021-01-13 op  - IRI support (RFC3987)
 31 286c4f40 2021-01-27 op  - punycode support
 32 b9220ca4 2021-01-11 op  - dual stack: can serve over both IPv4 and IPv6
 33 b9220ca4 2021-01-11 op  - CGI scripts
 34 b9220ca4 2021-01-11 op  - (very) low memory footprint
 35 b9220ca4 2021-01-11 op  - small codebase, easily hackable
 36 b9220ca4 2021-01-11 op  - virtual hosts
 37 286c4f40 2021-01-27 op  - per-location rules
 38 286c4f40 2021-01-27 op  - optional directory listings
 39 286c4f40 2021-01-27 op  - configurable mime types
 40 ea58dab1 2021-01-17 op  - sandboxed by default on OpenBSD, Linux and FreeBSD
 41 0b00962d 2021-01-25 op  - chroot support
 42 3e4749f7 2020-10-02 op 
 43 fab952e1 2020-10-03 op 
 44 b9220ca4 2021-01-11 op ## Drawbacks
 45 3e4749f7 2020-10-02 op 
 46 b9220ca4 2021-01-11 op  - not suited for very busy hosts.  If you receive an high number of
 47 b9220ca4 2021-01-11 op    connection per-second you'd probably want to run multiple gmid
 48 b9220ca4 2021-01-11 op    instances behind relayd/haproxy or a different server.
 49 85dff1f9 2021-01-11 op 
 50 286c4f40 2021-01-27 op 
 51 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
 52 286c4f40 2021-01-27 op 
 53 286c4f40 2021-01-27 op Even thought the current Gemini specification doesn't mention anything
 54 286c4f40 2021-01-27 op in this regard, I do think these are important things, so I tried to
 55 286c4f40 2021-01-27 op implement them in the most user-friendly way I could think of.
 56 286c4f40 2021-01-27 op 
 57 286c4f40 2021-01-27 op For starters, gmid has full support for IRI (RFC3987 --
 58 286c4f40 2021-01-27 op Internationalized Resource Identifiers).  IRIs are a superset of URI,
 59 286c4f40 2021-01-27 op so there aren't incompatibilities with URI-only clients.
 60 286c4f40 2021-01-27 op 
 61 286c4f40 2021-01-27 op There is full support also for punycode.  In theory, the users doesn't
 62 286c4f40 2021-01-27 op even need to know that punycode is a thing.  The hostname in the
 63 286c4f40 2021-01-27 op configuration file can (and must be) written with proper UNICODE, gmid
 64 286c4f40 2021-01-27 op will do the rest.
 65 286c4f40 2021-01-27 op 
 66 286c4f40 2021-01-27 op The only missing piece is UNICODE normalisation.  gmid doesn't
 67 286c4f40 2021-01-27 op do that (yet).
 68 286c4f40 2021-01-27 op 
 69 286c4f40 2021-01-27 op 
 70 b9220ca4 2021-01-11 op ## Building
 71 3e4749f7 2020-10-02 op 
 72 42650ade 2021-01-27 op gmid depends on a POSIX libc, OpenSSL/LibreSSL and libtls (provided
 73 42650ade 2021-01-27 op either by LibreSSL or libretls).  At build time, flex and yacc (or GNU
 74 42650ade 2021-01-27 op bison) are also needed.
 75 3e4749f7 2020-10-02 op 
 76 771d8f28 2021-01-17 op The build is as simple as
 77 3e4749f7 2020-10-02 op 
 78 b9220ca4 2021-01-11 op     make
 79 3e4749f7 2020-10-02 op 
 80 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
 81 f980545b 2021-01-21 op issue or notify me via email.
 82 8f0da580 2021-01-21 op 
 83 771d8f28 2021-01-17 op To install execute:
 84 881a9dd9 2021-01-16 op 
 85 771d8f28 2021-01-17 op     make install
 86 771d8f28 2021-01-17 op 
 87 17b09e3c 2021-01-18 op If you have trouble installing LibreSSL or libretls, as they aren't
 88 17b09e3c 2021-01-18 op available as package on various Linux distribution, you can use Docker
 89 17b09e3c 2021-01-18 op to build a `gmid` image with:
 90 771d8f28 2021-01-17 op 
 91 17b09e3c 2021-01-18 op     docker build -t gmid .
 92 17b09e3c 2021-01-18 op 
 93 17b09e3c 2021-01-18 op and then run it with something along the lines of
 94 17b09e3c 2021-01-18 op 
 95 17b09e3c 2021-01-18 op     docker run --rm -it -p 1965:1965 \
 96 6c117838 2021-01-25 op         -v /path/to/gmid.conf:...:ro \
 97 17b09e3c 2021-01-18 op         -v /path/to/docs:/var/gemini \
 98 6c117838 2021-01-25 op         gmid -c .../gmid.conf
 99 17b09e3c 2021-01-18 op 
100 6c117838 2021-01-25 op ellipses for brevity.
101 17b09e3c 2021-01-18 op 
102 dd8cc7d3 2021-01-22 op ### Local libretls
103 17b09e3c 2021-01-18 op 
104 8f0da580 2021-01-21 op This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
105 8f0da580 2021-01-21 op your distribution of choice or use docker instead.
106 8f0da580 2021-01-21 op 
107 8f0da580 2021-01-21 op However, it's possible to link `gmid` to locally-installed libtls
108 8f0da580 2021-01-21 op quite easily.  (It's how I test gmid on Fedora, for instance)
109 8f0da580 2021-01-21 op 
110 04397b32 2021-01-21 op Let's say you have compiled and installed libretls in `$LIBRETLS`,
111 8f0da580 2021-01-21 op then you can build `gmid` with
112 8f0da580 2021-01-21 op 
113 04397b32 2021-01-21 op     ./configure CFLAGS="-I$LIBRETLS/include" \
114 45b4aa6e 2021-01-23 op                 LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread"
115 8f0da580 2021-01-21 op     make
116 8f0da580 2021-01-21 op 
117 dd8cc7d3 2021-01-22 op ### Testing
118 dd8cc7d3 2021-01-22 op 
119 31a4993a 2021-01-23 op Execute
120 dd8cc7d3 2021-01-22 op 
121 dd8cc7d3 2021-01-22 op     make regress
122 dd8cc7d3 2021-01-22 op 
123 7f740a14 2021-01-22 op to start the suite.  Keep in mind that the suite will create files
124 dd8cc7d3 2021-01-22 op inside the `regress` directory and bind the 10965 port.
125 dd8cc7d3 2021-01-22 op 
126 dd8cc7d3 2021-01-22 op 
127 881a9dd9 2021-01-16 op ## Architecture/Security considerations
128 881a9dd9 2021-01-16 op 
129 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor.  The
130 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
131 881a9dd9 2021-01-16 op sandboxed.  When a CGI script needs to be executed, the executor
132 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
133 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
134 909ea500 2021-01-27 op This way, is still possible to execute CGI scripts without
135 909ea500 2021-01-27 op restrictions even in the presence of a sandbox.
136 881a9dd9 2021-01-16 op 
137 881a9dd9 2021-01-16 op On OpenBSD, the listener process runs with the `stdio recvfd rpath
138 42650ade 2021-01-27 op inet` pledges, the executor has `stdio sendfd proc exec` as pledges;
139 42650ade 2021-01-27 op both have unveiled only the served directories.
140 881a9dd9 2021-01-16 op 
141 ea58dab1 2021-01-17 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
142 d939d0f0 2021-01-17 op 
143 76fd55f4 2021-01-17 op On Linux, a `seccomp(2)` filter is installed to allow only certain
144 76fd55f4 2021-01-17 op syscalls, see [sandbox.c](sandbox.c) for more information on the BPF
145 ea58dab1 2021-01-17 op program.
146 ea58dab1 2021-01-17 op 
147 ea58dab1 2021-01-17 op In any case, you are invited to run gmid inside some sort of
148 0b00962d 2021-01-25 op container/jail/chroot.