1 b9220ca4 2021-01-11 op # gmid
  2 3e4749f7 2020-10-02 op 
  3 601bc1cc 2021-01-30 op gmid is a Gemini server written with security in mind.  I initially
  4 601bc1cc 2021-01-30 op wrote it to serve static files, but it has grown into a featureful
  5 601bc1cc 2021-01-30 op server that can be used from either the command line to serve local
  6 601bc1cc 2021-01-30 op directories
  7 3e4749f7 2020-10-02 op 
  8 601bc1cc 2021-01-30 op     gmid docs  # serve the directory docs over gemini
  9 3e4749f7 2020-10-02 op 
 10 601bc1cc 2021-01-30 op or as a traditional daemon
 11 3e4749f7 2020-10-02 op 
 12 2f09adb0 2021-01-25 op     gmid -c /etc/gmid.conf
 13 2f09adb0 2021-01-25 op 
 14 2f09adb0 2021-01-25 op 
 15 b9220ca4 2021-01-11 op ## Features
 16 3e4749f7 2020-10-02 op 
 17 601bc1cc 2021-01-30 op (random order)
 18 601bc1cc 2021-01-30 op 
 19 86edc4f4 2021-02-04 op  - reconfiguration: reload the running configuration without interruption
 20 86edc4f4 2021-02-04 op  - sandboxed by default on OpenBSD, Linux and FreeBSD
 21 4d2ec6d7 2021-01-13 op  - IRI support (RFC3987)
 22 286c4f40 2021-01-27 op  - punycode support
 23 601bc1cc 2021-01-30 op  - dual stack (IPv4 and IPv6)
 24 601bc1cc 2021-01-30 op  - automatic certificate generation for config-less mode
 25 b9220ca4 2021-01-11 op  - CGI scripts
 26 b9220ca4 2021-01-11 op  - (very) low memory footprint
 27 b9220ca4 2021-01-11 op  - small codebase, easily hackable
 28 b9220ca4 2021-01-11 op  - virtual hosts
 29 286c4f40 2021-01-27 op  - per-location rules
 30 286c4f40 2021-01-27 op  - optional directory listings
 31 286c4f40 2021-01-27 op  - configurable mime types
 32 0b00962d 2021-01-25 op  - chroot support
 33 3e4749f7 2020-10-02 op 
 34 fab952e1 2020-10-03 op 
 35 b9220ca4 2021-01-11 op ## Drawbacks
 36 3e4749f7 2020-10-02 op 
 37 b9220ca4 2021-01-11 op  - not suited for very busy hosts.  If you receive an high number of
 38 b9220ca4 2021-01-11 op    connection per-second you'd probably want to run multiple gmid
 39 b9220ca4 2021-01-11 op    instances behind relayd/haproxy or a different server.
 40 85dff1f9 2021-01-11 op 
 41 286c4f40 2021-01-27 op 
 42 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
 43 286c4f40 2021-01-27 op 
 44 286c4f40 2021-01-27 op Even thought the current Gemini specification doesn't mention anything
 45 601bc1cc 2021-01-30 op in this regard, I do think these are important things and so I tried
 46 601bc1cc 2021-01-30 op to implement them in the most user-friendly way I could think of.
 47 286c4f40 2021-01-27 op 
 48 601bc1cc 2021-01-30 op For starters, gmid has full support for IRI (RFC3987 —
 49 22a742e4 2021-01-29 op Internationalized Resource Identifiers).  IRIs are a superset of URIs,
 50 286c4f40 2021-01-27 op so there aren't incompatibilities with URI-only clients.
 51 286c4f40 2021-01-27 op 
 52 601bc1cc 2021-01-30 op There is full support also for punycode.  In theory, the user doesn't
 53 286c4f40 2021-01-27 op even need to know that punycode is a thing.  The hostname in the
 54 601bc1cc 2021-01-30 op configuration file can (and must be) in the decoded form (e.g. `naïve`
 55 601bc1cc 2021-01-30 op and not `xn--nave-6pa`), gmid will do the rest.
 56 286c4f40 2021-01-27 op 
 57 601bc1cc 2021-01-30 op The only missing piece is UNICODE normalisation of the IRI path: gmid
 58 601bc1cc 2021-01-30 op doesn't do that (yet).
 59 286c4f40 2021-01-27 op 
 60 286c4f40 2021-01-27 op 
 61 1487e11e 2021-02-06 op ## Configuration
 62 1487e11e 2021-02-06 op 
 63 1487e11e 2021-02-06 op gmid has a rich configuration file, heavily inspired by OpenBSD'
 64 1487e11e 2021-02-06 op httpd.  While you should definitely check the manpage because it
 65 1487e11e 2021-02-06 op documents every option in depth, here's an example of what gmid can
 66 1487e11e 2021-02-06 op do.
 67 1487e11e 2021-02-06 op 
 68 1487e11e 2021-02-06 op ```conf
 69 1487e11e 2021-02-06 op ipv6 on     # enable ipv6
 70 1487e11e 2021-02-06 op 
 71 1487e11e 2021-02-06 op server "example.com" {
 72 1487e11e 2021-02-06 op     cert "/path/to/cert.pem"
 73 1487e11e 2021-02-06 op     key  "/path/to/key.pem"
 74 1487e11e 2021-02-06 op     root "/var/gemini/example.com"
 75 1487e11e 2021-02-06 op     lang "it"
 76 1487e11e 2021-02-06 op     cgi  "/cgi/*"
 77 1487e11e 2021-02-06 op 
 78 1487e11e 2021-02-06 op     location "/files/*" {
 79 1487e11e 2021-02-06 op         auto index on
 80 1487e11e 2021-02-06 op     }
 81 1487e11e 2021-02-06 op 
 82 1487e11e 2021-02-06 op     location "/repo/*" {
 83 1487e11e 2021-02-06 op         # change the index file name
 84 1487e11e 2021-02-06 op         index "README.gmi"
 85 1487e11e 2021-02-06 op     }
 86 1487e11e 2021-02-06 op 
 87 1487e11e 2021-02-06 op     # redirect /cgi/man/... to man.example.com/...
 88 1487e11e 2021-02-06 op     location "/cgi/man*" {
 89 1487e11e 2021-02-06 op         strip 2
 90 1487e11e 2021-02-06 op         block return 31 "gemini://man.example.com%p"
 91 1487e11e 2021-02-06 op     }
 92 1487e11e 2021-02-06 op }
 93 1487e11e 2021-02-06 op 
 94 1487e11e 2021-02-06 op server "man.example.com" {
 95 1487e11e 2021-02-06 op     cert "..."
 96 1487e11e 2021-02-06 op     key  "..."
 97 1487e11e 2021-02-06 op     root "/var/gemini/man.example.com"
 98 1487e11e 2021-02-06 op 
 99 1487e11e 2021-02-06 op     # handle every request with the CGI script `man'
100 1487e11e 2021-02-06 op     entrypoint "man"
101 1487e11e 2021-02-06 op }
102 1487e11e 2021-02-06 op ```
103 1487e11e 2021-02-06 op 
104 1487e11e 2021-02-06 op 
105 b9220ca4 2021-01-11 op ## Building
106 3e4749f7 2020-10-02 op 
107 42650ade 2021-01-27 op gmid depends on a POSIX libc, OpenSSL/LibreSSL and libtls (provided
108 42650ade 2021-01-27 op either by LibreSSL or libretls).  At build time, flex and yacc (or GNU
109 42650ade 2021-01-27 op bison) are also needed.
110 3e4749f7 2020-10-02 op 
111 771d8f28 2021-01-17 op The build is as simple as
112 3e4749f7 2020-10-02 op 
113 601bc1cc 2021-01-30 op     ./configure
114 b9220ca4 2021-01-11 op     make
115 3e4749f7 2020-10-02 op 
116 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
117 f980545b 2021-01-21 op issue or notify me via email.
118 8f0da580 2021-01-21 op 
119 771d8f28 2021-01-17 op To install execute:
120 881a9dd9 2021-01-16 op 
121 771d8f28 2021-01-17 op     make install
122 771d8f28 2021-01-17 op 
123 601bc1cc 2021-01-30 op ### Docker
124 771d8f28 2021-01-17 op 
125 601bc1cc 2021-01-30 op If you have trouble installing LibreSSL or libretls, you can use
126 601bc1cc 2021-01-30 op Docker to build a `gmid` image with:
127 601bc1cc 2021-01-30 op 
128 17b09e3c 2021-01-18 op     docker build -t gmid .
129 17b09e3c 2021-01-18 op 
130 17b09e3c 2021-01-18 op and then run it with something along the lines of
131 17b09e3c 2021-01-18 op 
132 17b09e3c 2021-01-18 op     docker run --rm -it -p 1965:1965 \
133 6c117838 2021-01-25 op         -v /path/to/gmid.conf:...:ro \
134 17b09e3c 2021-01-18 op         -v /path/to/docs:/var/gemini \
135 6c117838 2021-01-25 op         gmid -c .../gmid.conf
136 17b09e3c 2021-01-18 op 
137 601bc1cc 2021-01-30 op (ellipses used for brevity)
138 17b09e3c 2021-01-18 op 
139 dd8cc7d3 2021-01-22 op ### Local libretls
140 17b09e3c 2021-01-18 op 
141 8f0da580 2021-01-21 op This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
142 8f0da580 2021-01-21 op your distribution of choice or use docker instead.
143 8f0da580 2021-01-21 op 
144 601bc1cc 2021-01-30 op However, it's possible to statically-link `gmid` to locally-installed
145 601bc1cc 2021-01-30 op libretls quite easily.  (It's how I test gmid on Fedora, for instance)
146 8f0da580 2021-01-21 op 
147 04397b32 2021-01-21 op Let's say you have compiled and installed libretls in `$LIBRETLS`,
148 8f0da580 2021-01-21 op then you can build `gmid` with
149 8f0da580 2021-01-21 op 
150 04397b32 2021-01-21 op     ./configure CFLAGS="-I$LIBRETLS/include" \
151 45b4aa6e 2021-01-23 op                 LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread"
152 8f0da580 2021-01-21 op     make
153 8f0da580 2021-01-21 op 
154 dd8cc7d3 2021-01-22 op ### Testing
155 dd8cc7d3 2021-01-22 op 
156 31a4993a 2021-01-23 op Execute
157 dd8cc7d3 2021-01-22 op 
158 dd8cc7d3 2021-01-22 op     make regress
159 dd8cc7d3 2021-01-22 op 
160 601bc1cc 2021-01-30 op to start the suite.  Keep in mind that the regression tests will
161 601bc1cc 2021-01-30 op create files inside the `regress` directory and bind the 10965 port.
162 dd8cc7d3 2021-01-22 op 
163 dd8cc7d3 2021-01-22 op 
164 881a9dd9 2021-01-16 op ## Architecture/Security considerations
165 881a9dd9 2021-01-16 op 
166 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor.  The
167 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
168 881a9dd9 2021-01-16 op sandboxed.  When a CGI script needs to be executed, the executor
169 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
170 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
171 909ea500 2021-01-27 op This way, is still possible to execute CGI scripts without
172 601bc1cc 2021-01-30 op restrictions even in the presence of a sandboxed network process.
173 881a9dd9 2021-01-16 op 
174 601bc1cc 2021-01-30 op On OpenBSD, the listener runs with the `stdio recvfd rpath inet`
175 601bc1cc 2021-01-30 op pledges, while the executor has `stdio sendfd proc exec`; both have
176 601bc1cc 2021-01-30 op unveiled only the served directories.
177 881a9dd9 2021-01-16 op 
178 ea58dab1 2021-01-17 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
179 d939d0f0 2021-01-17 op 
180 601bc1cc 2021-01-30 op On Linux, a `seccomp(2)` filter is installed in the listener to allow
181 601bc1cc 2021-01-30 op only certain syscalls, see [sandbox.c](sandbox.c) for more information
182 601bc1cc 2021-01-30 op on the BPF program.
183 ea58dab1 2021-01-17 op 
184 ea58dab1 2021-01-17 op In any case, you are invited to run gmid inside some sort of
185 0b00962d 2021-01-25 op container/jail/chroot.