3 b9231167 2021-02-08 op gmid is a fast Gemini server written with security in mind. I
4 b9231167 2021-02-08 op initially wrote it to serve static files, but it has grown into a
5 747b35d0 2021-02-08 op featureful server.
10 601bc1cc 2021-01-30 op (random order)
12 08ce6f52 2021-04-29 op - sandboxed by default on OpenBSD, Linux and FreeBSD
13 747b35d0 2021-02-08 op - reconfiguration: reload the running configuration without
15 290b5baa 2021-02-23 op - automatic redirect/error pages (see `block return`)
16 4d2ec6d7 2021-01-13 op - IRI support (RFC3987)
17 601bc1cc 2021-01-30 op - automatic certificate generation for config-less mode
18 a6c80955 2021-06-11 op - CGI and FastCGI support
19 08ce6f52 2021-04-29 op - virtual hosts
20 08ce6f52 2021-04-29 op - location rules
21 b9231167 2021-02-08 op - event-based asynchronous I/O model
22 08ce6f52 2021-04-29 op - low memory footprint
23 b9220ca4 2021-01-11 op - small codebase, easily hackable
26 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
28 286c4f40 2021-01-27 op Even thought the current Gemini specification doesn't mention anything
29 601bc1cc 2021-01-30 op in this regard, I do think these are important things and so I tried
30 601bc1cc 2021-01-30 op to implement them in the most user-friendly way I could think of.
32 601bc1cc 2021-01-30 op For starters, gmid has full support for IRI (RFC3987 —
33 22a742e4 2021-01-29 op Internationalized Resource Identifiers). IRIs are a superset of URIs,
34 286c4f40 2021-01-27 op so there aren't incompatibilities with URI-only clients.
36 601bc1cc 2021-01-30 op There is full support also for punycode. In theory, the user doesn't
37 286c4f40 2021-01-27 op even need to know that punycode is a thing. The hostname in the
38 601bc1cc 2021-01-30 op configuration file can (and must be) in the decoded form (e.g. `naïve`
39 601bc1cc 2021-01-30 op and not `xn--nave-6pa`), gmid will do the rest.
41 601bc1cc 2021-01-30 op The only missing piece is UNICODE normalisation of the IRI path: gmid
42 601bc1cc 2021-01-30 op doesn't do that (yet).
45 1487e11e 2021-02-06 op ## Configuration
47 1487e11e 2021-02-06 op gmid has a rich configuration file, heavily inspired by OpenBSD'
48 08ce6f52 2021-04-29 op httpd, with every detail carefully documented in the manpage. Here's
49 08ce6f52 2021-04-29 op a minimal example of a config file:
52 08ce6f52 2021-04-29 op server "example.com" {
53 08ce6f52 2021-04-29 op cert "/path/to/cert.pem"
54 08ce6f52 2021-04-29 op key "/path/to/key.pem"
55 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
59 3759d3eb 2021-07-06 op and a slightly more complex one
62 1487e11e 2021-02-06 op ipv6 on # enable ipv6
64 3759d3eb 2021-07-06 op # define a macro
65 3759d3eb 2021-07-06 op cert_root = "/path/to/keys"
67 1487e11e 2021-02-06 op server "example.com" {
68 08ce6f52 2021-04-29 op alias "foobar.com"
70 3759d3eb 2021-07-06 op cert $cert_root "/example.com.crt"
71 3759d3eb 2021-07-06 op key $cert_root "/example.com.pem"
72 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
74 08ce6f52 2021-04-29 op # lang for text/gemini files
77 08ce6f52 2021-04-29 op # execute CGI scripts in /cgi/
80 08ce6f52 2021-04-29 op # only for locations that matches /files/*
81 08ce6f52 2021-04-29 op location "/files/*" {
82 08ce6f52 2021-04-29 op # generate directory listings
86 08ce6f52 2021-04-29 op location "/repo/*" {
87 08ce6f52 2021-04-29 op # change the index file name
88 08ce6f52 2021-04-29 op index "README.gmi"
97 b9231167 2021-02-08 op gmid depends on a POSIX libc, libevent2, OpenSSL/LibreSSL and libtls
98 74f0778b 2021-06-16 op (provided either by LibreSSL or libretls). At build time, yacc (or
99 74f0778b 2021-06-16 op GNU bison) is also needed.
101 771d8f28 2021-01-17 op The build is as simple as
106 2ddc9271 2021-03-29 op or `make static` to build a statically-linked executable.
108 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
109 f980545b 2021-01-21 op issue or notify me via email.
111 771d8f28 2021-01-17 op To install execute:
115 bb4be662 2021-04-25 op Please keep in mind that the master branch, from time to time, may be
116 bb4be662 2021-04-25 op accidentally broken on some platforms. gmid is developed primarily on
117 bb4be662 2021-04-25 op OpenBSD/amd64 and commits on the master branch don't get always tested
118 bb4be662 2021-04-25 op in other OSes. Before tagging a release however, a comprehensive
119 c79b63f5 2021-04-27 op testing on various platform is done to ensure that everything is
120 c79b63f5 2021-04-27 op working as intended.
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:
128 17b09e3c 2021-01-18 op docker build -t gmid .
130 17b09e3c 2021-01-18 op and then run it with something along the lines of
132 17b09e3c 2021-01-18 op docker run --rm -it -p 1965:1965 \
133 0c7a1d3c 2021-06-04 op -v /path/to/gmid.conf:/etc/gmid.conf:ro \
134 17b09e3c 2021-01-18 op -v /path/to/docs:/var/gemini \
135 0c7a1d3c 2021-06-04 op gmid /bin/gmid -c /etc/gmid.conf
138 dd8cc7d3 2021-01-22 op ### Local libretls
140 8f0da580 2021-01-21 op This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
141 8f0da580 2021-01-21 op your distribution of choice or use docker instead.
143 601bc1cc 2021-01-30 op However, it's possible to statically-link `gmid` to locally-installed
144 601bc1cc 2021-01-30 op libretls quite easily. (It's how I test gmid on Fedora, for instance)
146 04397b32 2021-01-21 op Let's say you have compiled and installed libretls in `$LIBRETLS`,
147 8f0da580 2021-01-21 op then you can build `gmid` with
149 04397b32 2021-01-21 op ./configure CFLAGS="-I$LIBRETLS/include" \
150 1606927e 2021-02-11 op LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread -levent"
159 601bc1cc 2021-01-30 op to start the suite. Keep in mind that the regression tests will
160 601bc1cc 2021-01-30 op create files inside the `regress` directory and bind the 10965 port.
163 881a9dd9 2021-01-16 op ## Architecture/Security considerations
165 290b5baa 2021-02-23 op gmid is composed by four processes: the parent process, the logger,
166 290b5baa 2021-02-23 op the listener and the executor. The parent process is the only one
167 290b5baa 2021-02-23 op that doesn't drop privileges, but all it does is to wait for a SIGHUP
168 290b5baa 2021-02-23 op to reload the configuration and spawn a new generation of children
169 290b5baa 2021-02-23 op process. The logger processes gather the logs and prints 'em to
170 290b5baa 2021-02-23 op stderr or syslog (for the time being.) The listener process is the
171 290b5baa 2021-02-23 op only one that needs internet access and is sandboxed by default. The
172 290b5baa 2021-02-23 op executor process exists only to fork and execute CGI scripts.
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 290b5baa 2021-02-23 op unveiled only the served directories. The logger process has pledge
179 94be0bf0 2021-03-20 op On FreeBSD, the listener and logger process are sandboxed with `capsicum(4)`.
181 601bc1cc 2021-01-30 op On Linux, a `seccomp(2)` filter is installed in the listener to allow
182 601bc1cc 2021-01-30 op only certain syscalls, see [sandbox.c](sandbox.c) for more information
183 601bc1cc 2021-01-30 op on the BPF program.
185 6957a8c2 2021-06-04 op In any case, it's advisable to run gmid inside some sort of
186 0b00962d 2021-01-25 op container/jail/chroot.