3 gmid is a fast Gemini server written with security in mind. I
4 initially wrote it to serve static files, but it has grown into a
12 - reconfiguration: reload the running configuration without
14 - sandboxed by default on OpenBSD, Linux and FreeBSD
15 - automatic redirect/error pages (see `block return`)
16 - IRI support (RFC3987)
18 - dual stack (IPv4 and IPv6)
19 - automatic certificate generation for config-less mode
21 - low memory footprint
22 - event-based asynchronous I/O model
23 - small codebase, easily hackable
26 - optional directory listings
27 - configurable mime types
31 ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
33 Even thought the current Gemini specification doesn't mention anything
34 in this regard, I do think these are important things and so I tried
35 to implement them in the most user-friendly way I could think of.
37 For starters, gmid has full support for IRI (RFC3987 —
38 Internationalized Resource Identifiers). IRIs are a superset of URIs,
39 so there aren't incompatibilities with URI-only clients.
41 There is full support also for punycode. In theory, the user doesn't
42 even need to know that punycode is a thing. The hostname in the
43 configuration file can (and must be) in the decoded form (e.g. `naïve`
44 and not `xn--nave-6pa`), gmid will do the rest.
46 The only missing piece is UNICODE normalisation of the IRI path: gmid
47 doesn't do that (yet).
52 gmid has a rich configuration file, heavily inspired by OpenBSD'
53 httpd. While you should definitely check the manpage because it
54 documents every option in depth, here's a small example of how a
55 configuration file looks like.
60 server "example.com" {
61 cert "/path/to/cert.pem"
62 key "/path/to/key.pem"
63 root "/var/gemini/example.com"
72 # change the index file name
81 gmid depends on a POSIX libc, libevent2, OpenSSL/LibreSSL and libtls
82 (provided either by LibreSSL or libretls). At build time, flex and
83 yacc (or GNU bison) are also needed.
85 The build is as simple as
90 If the configure scripts fails to pick up something, please open an
91 issue or notify me via email.
99 If you have trouble installing LibreSSL or libretls, you can use
100 Docker to build a `gmid` image with:
102 docker build -t gmid .
104 and then run it with something along the lines of
106 docker run --rm -it -p 1965:1965 \
107 -v /path/to/gmid.conf:...:ro \
108 -v /path/to/docs:/var/gemini \
109 gmid -c .../gmid.conf
111 (ellipses used for brevity)
115 This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
116 your distribution of choice or use docker instead.
118 However, it's possible to statically-link `gmid` to locally-installed
119 libretls quite easily. (It's how I test gmid on Fedora, for instance)
121 Let's say you have compiled and installed libretls in `$LIBRETLS`,
122 then you can build `gmid` with
124 ./configure CFLAGS="-I$LIBRETLS/include" \
125 LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread -levent"
134 to start the suite. Keep in mind that the regression tests will
135 create files inside the `regress` directory and bind the 10965 port.
138 ## Architecture/Security considerations
140 gmid is composed by four processes: the parent process, the logger,
141 the listener and the executor. The parent process is the only one
142 that doesn't drop privileges, but all it does is to wait for a SIGHUP
143 to reload the configuration and spawn a new generation of children
144 process. The logger processes gather the logs and prints 'em to
145 stderr or syslog (for the time being.) The listener process is the
146 only one that needs internet access and is sandboxed by default. The
147 executor process exists only to fork and execute CGI scripts.
149 On OpenBSD, the listener runs with the `stdio recvfd rpath inet`
150 pledges, while the executor has `stdio sendfd proc exec`; both have
151 unveiled only the served directories. The logger process has pledge
154 On FreeBSD, the listener and logger process are sandboxed with `capsicum(4)`.
156 On Linux, a `seccomp(2)` filter is installed in the listener to allow
157 only certain syscalls, see [sandbox.c](sandbox.c) for more information
160 In any case, you are invited to run gmid inside some sort of
161 container/jail/chroot.