1 b9220ca4 2021-01-11 op # gmid
 2 3e4749f7 2020-10-02 op 
 3 b9220ca4 2021-01-11 op > dead simple, zero configuration Gemini server
 4 3e4749f7 2020-10-02 op 
 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.
 9 3e4749f7 2020-10-02 op 
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 881a9dd9 2021-01-16 op mind: on FreeBSD and OpenBSD is sandboxed via `capsicum(4)`and
13 881a9dd9 2021-01-16 op `pledge(2)`/`unveil(2)` respectively.
14 3e4749f7 2020-10-02 op 
15 3e4749f7 2020-10-02 op 
16 b9220ca4 2021-01-11 op ## Features
17 3e4749f7 2020-10-02 op 
18 4d2ec6d7 2021-01-13 op  - IRI support (RFC3987)
19 b9220ca4 2021-01-11 op  - dual stack: can serve over both IPv4 and IPv6
20 b9220ca4 2021-01-11 op  - CGI scripts
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 881a9dd9 2021-01-16 op  - sandboxed by default on OpenBSD and FreeBSD
25 3e4749f7 2020-10-02 op 
26 fab952e1 2020-10-03 op 
27 b9220ca4 2021-01-11 op ## Drawbacks
28 3e4749f7 2020-10-02 op 
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.
32 85dff1f9 2021-01-11 op 
33 b9220ca4 2021-01-11 op ## Building
34 3e4749f7 2020-10-02 op 
35 b9220ca4 2021-01-11 op gmid depends a POSIX libc and libtls.  It can probably be linked
36 b9220ca4 2021-01-11 op against libretls, but I've never tried.
37 3e4749f7 2020-10-02 op 
38 b9220ca4 2021-01-11 op See [INSTALL.gmi](INSTALL.gmi) for more info, but the build is as
39 b9220ca4 2021-01-11 op simple as
40 3e4749f7 2020-10-02 op 
41 b9220ca4 2021-01-11 op     make
42 3e4749f7 2020-10-02 op 
43 b9220ca4 2021-01-11 op The Makefile isn't able to produce a statically linked executable
44 b9220ca4 2021-01-11 op (yet), so for that you have to execute by hand
45 d7802bb4 2020-12-02 op 
46 b9220ca4 2021-01-11 op     make
47 b9220ca4 2021-01-11 op     cc -static *.o /usr/lib/lib{crypto,tls,ssl}.a -o gmid
48 b9220ca4 2021-01-11 op     strip gmid
49 d7802bb4 2020-12-02 op 
50 b9220ca4 2021-01-11 op to enjoy your ~2.3M statically-linked gmid.
51 881a9dd9 2021-01-16 op 
52 881a9dd9 2021-01-16 op 
53 881a9dd9 2021-01-16 op ## Architecture/Security considerations
54 881a9dd9 2021-01-16 op 
55 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor.  The
56 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
57 881a9dd9 2021-01-16 op sandboxed.  When a CGI script needs to be executed, the executor
58 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
59 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
60 881a9dd9 2021-01-16 op This way, is still possible to execute CGI scripts without restriction
61 881a9dd9 2021-01-16 op even if the presence of a sandbox.
62 881a9dd9 2021-01-16 op 
63 881a9dd9 2021-01-16 op On OpenBSD, the listener process runs with the `stdio recvfd rpath
64 881a9dd9 2021-01-16 op inet` pledges and has `unveil(2)`ed only the directories that it
65 881a9dd9 2021-01-16 op serves; the executor has `stdio sendfd proc exec` as pledges.
66 881a9dd9 2021-01-16 op 
67 881a9dd9 2021-01-16 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.