3 b9220ca4 2021-01-11 op > dead simple, zero configuration Gemini server
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.
10 881a9dd9 2021-01-16 op gmid 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.
18 4d2ec6d7 2021-01-13 op - IRI support (RFC3987)
19 b9220ca4 2021-01-11 op - dual stack: can serve over both IPv4 and IPv6
21 b9220ca4 2021-01-11 op - (very) low memory footprint
22 b9220ca4 2021-01-11 op - small codebase, easily hackable
23 b9220ca4 2021-01-11 op - virtual hosts
24 ea58dab1 2021-01-17 op - sandboxed by default on OpenBSD, Linux and FreeBSD
29 b9220ca4 2021-01-11 op - not suited for very busy hosts. If you receive an high number of
30 b9220ca4 2021-01-11 op connection per-second you'd probably want to run multiple gmid
31 b9220ca4 2021-01-11 op instances behind relayd/haproxy or a different server.
35 5f564d23 2021-01-17 op gmid depends on a POSIX libc and libtls (provided either by LibreSSL
36 5f564d23 2021-01-17 op or libretls). At build time, flex and yacc (or GNU bison) are also
39 771d8f28 2021-01-17 op The build is as simple as
47 b9220ca4 2021-01-11 op to enjoy your ~2.3M statically-linked gmid.
49 771d8f28 2021-01-17 op To install execute:
53 17b09e3c 2021-01-18 op If you have trouble installing LibreSSL or libretls, as they aren't
54 17b09e3c 2021-01-18 op available as package on various Linux distribution, you can use Docker
55 17b09e3c 2021-01-18 op to build a `gmid` image with:
57 17b09e3c 2021-01-18 op docker build -t gmid .
59 17b09e3c 2021-01-18 op and then run it with something along the lines of
61 17b09e3c 2021-01-18 op docker run --rm -it -p 1965:1965 \
62 17b09e3c 2021-01-18 op -v /path/to/cert.pem:...:ro \
63 17b09e3c 2021-01-18 op -v /path/to/key.pem:...:ro \
64 17b09e3c 2021-01-18 op -v /path/to/docs:/var/gemini \
65 17b09e3c 2021-01-18 op gmid -f -d /var/gemini -K ... -C ...
67 17b09e3c 2021-01-18 op ellipses used for brevity.
70 881a9dd9 2021-01-16 op ## Architecture/Security considerations
72 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor. The
73 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
74 881a9dd9 2021-01-16 op sandboxed. When a CGI script needs to be executed, the executor
75 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
76 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
77 881a9dd9 2021-01-16 op This way, is still possible to execute CGI scripts without restriction
78 881a9dd9 2021-01-16 op even if the presence of a sandbox.
80 881a9dd9 2021-01-16 op On OpenBSD, the listener process runs with the `stdio recvfd rpath
81 881a9dd9 2021-01-16 op inet` pledges and has `unveil(2)`ed only the directories that it
82 ea58dab1 2021-01-17 op serves; the executor has `stdio sendfd proc exec` as pledges.
84 ea58dab1 2021-01-17 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
86 76fd55f4 2021-01-17 op On Linux, a `seccomp(2)` filter is installed to allow only certain
87 76fd55f4 2021-01-17 op syscalls, see [sandbox.c](sandbox.c) for more information on the BPF
90 ea58dab1 2021-01-17 op In any case, you are invited to run gmid inside some sort of
91 ea58dab1 2021-01-17 op container/jail.