1 # gmid
2 
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
5 featureful server.
6 
7 
8 ## Features
9 
10 (random order)
11 
12  - reconfiguration: reload the running configuration without
13    interruption
14  - sandboxed by default on OpenBSD, Linux and FreeBSD
15  - automatic redirect/error pages (see `block return`)
16  - IRI support (RFC3987)
17  - punycode support
18  - dual stack (IPv4 and IPv6)
19  - automatic certificate generation for config-less mode
20  - CGI scripts
21  - low memory footprint
22  - event-based asynchronous I/O model
23  - small codebase, easily hackable
24  - virtual hosts
25  - per-location rules
26  - optional directory listings
27  - configurable mime types
28  - chroot support
29 
30 
31 ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
32 
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.
36 
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.
40 
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.
45 
46 The only missing piece is UNICODE normalisation of the IRI path: gmid
47 doesn't do that (yet).
48 
49 
50 ## Configuration
51 
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.
56 
57 ```conf
58 ipv6 on     # enable ipv6
59 
60 server "example.com" {
61     cert "/path/to/cert.pem"
62     key  "/path/to/key.pem"
63     root "/var/gemini/example.com"
64     lang "it"
65     cgi  "/cgi/*"
66 
67     location "/files/*" {
68         auto index on
69     }
70 
71     location "/repo/*" {
72         # change the index file name
73         index "README.gmi"
74     }
75 }
76 ```
77 
78 
79 ## Building
80 
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.
84 
85 The build is as simple as
86 
87     ./configure
88     make
89 
90 If the configure scripts fails to pick up something, please open an
91 issue or notify me via email.
92 
93 To install execute:
94 
95     make install
96 
97 ### Docker
98 
99 If you have trouble installing LibreSSL or libretls, you can use
100 Docker to build a `gmid` image with:
101 
102     docker build -t gmid .
103 
104 and then run it with something along the lines of
105 
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
110 
111 (ellipses used for brevity)
112 
113 ### Local libretls
114 
115 This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
116 your distribution of choice or use docker instead.
117 
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)
120 
121 Let's say you have compiled and installed libretls in `$LIBRETLS`,
122 then you can build `gmid` with
123 
124     ./configure CFLAGS="-I$LIBRETLS/include" \
125                 LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread -levent"
126     make
127 
128 ### Testing
129 
130 Execute
131 
132     make regress
133 
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.
136 
137 
138 ## Architecture/Security considerations
139 
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.
148 
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
152 `stdio`.
153 
154 On FreeBSD, the listener process is sandboxed with `capsicum(4)`.
155 
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
158 on the BPF program.
159 
160 In any case, you are invited to run gmid inside some sort of
161 container/jail/chroot.