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
8 601bc1cc 2021-01-30 op gmid docs # serve the directory docs over gemini
10 601bc1cc 2021-01-30 op or as a traditional daemon
12 2f09adb0 2021-01-25 op gmid -c /etc/gmid.conf
17 601bc1cc 2021-01-30 op (random order)
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
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
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.
42 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
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.
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.
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.
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).
63 42650ade 2021-01-27 op gmid depends on a POSIX libc, OpenSSL/LibreSSL and libtls (provided
64 42650ade 2021-01-27 op either by LibreSSL or libretls). At build time, flex and yacc (or GNU
65 42650ade 2021-01-27 op bison) are also needed.
67 771d8f28 2021-01-17 op The build is as simple as
72 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
73 f980545b 2021-01-21 op issue or notify me via email.
75 771d8f28 2021-01-17 op To install execute:
81 601bc1cc 2021-01-30 op If you have trouble installing LibreSSL or libretls, you can use
82 601bc1cc 2021-01-30 op Docker to build a `gmid` image with:
84 17b09e3c 2021-01-18 op docker build -t gmid .
86 17b09e3c 2021-01-18 op and then run it with something along the lines of
88 17b09e3c 2021-01-18 op docker run --rm -it -p 1965:1965 \
89 6c117838 2021-01-25 op -v /path/to/gmid.conf:...:ro \
90 17b09e3c 2021-01-18 op -v /path/to/docs:/var/gemini \
91 6c117838 2021-01-25 op gmid -c .../gmid.conf
93 601bc1cc 2021-01-30 op (ellipses used for brevity)
95 dd8cc7d3 2021-01-22 op ### Local libretls
97 8f0da580 2021-01-21 op This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
98 8f0da580 2021-01-21 op your distribution of choice or use docker instead.
100 601bc1cc 2021-01-30 op However, it's possible to statically-link `gmid` to locally-installed
101 601bc1cc 2021-01-30 op libretls quite easily. (It's how I test gmid on Fedora, for instance)
103 04397b32 2021-01-21 op Let's say you have compiled and installed libretls in `$LIBRETLS`,
104 8f0da580 2021-01-21 op then you can build `gmid` with
106 04397b32 2021-01-21 op ./configure CFLAGS="-I$LIBRETLS/include" \
107 45b4aa6e 2021-01-23 op LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread"
116 601bc1cc 2021-01-30 op to start the suite. Keep in mind that the regression tests will
117 601bc1cc 2021-01-30 op create files inside the `regress` directory and bind the 10965 port.
120 881a9dd9 2021-01-16 op ## Architecture/Security considerations
122 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor. The
123 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
124 881a9dd9 2021-01-16 op sandboxed. When a CGI script needs to be executed, the executor
125 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
126 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
127 909ea500 2021-01-27 op This way, is still possible to execute CGI scripts without
128 601bc1cc 2021-01-30 op restrictions even in the presence of a sandboxed network process.
130 601bc1cc 2021-01-30 op On OpenBSD, the listener runs with the `stdio recvfd rpath inet`
131 601bc1cc 2021-01-30 op pledges, while the executor has `stdio sendfd proc exec`; both have
132 601bc1cc 2021-01-30 op unveiled only the served directories.
134 ea58dab1 2021-01-17 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
136 601bc1cc 2021-01-30 op On Linux, a `seccomp(2)` filter is installed in the listener to allow
137 601bc1cc 2021-01-30 op only certain syscalls, see [sandbox.c](sandbox.c) for more information
138 601bc1cc 2021-01-30 op on the BPF program.
140 ea58dab1 2021-01-17 op In any case, you are invited to run gmid inside some sort of
141 0b00962d 2021-01-25 op container/jail/chroot.
