Blame


1 b9220ca4 2021-01-11 op # gmid
2 3e4749f7 2020-10-02 op
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.
6 3e4749f7 2020-10-02 op
7 3e4749f7 2020-10-02 op
8 b9220ca4 2021-01-11 op ## Features
9 3e4749f7 2020-10-02 op
10 601bc1cc 2021-01-30 op (random order)
11 601bc1cc 2021-01-30 op
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
14 747b35d0 2021-02-08 op interruption
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 c3eb759a 2021-12-29 op - reverse proxying
19 d29a2ee2 2022-09-06 op - FastCGI support
20 08ce6f52 2021-04-29 op - virtual hosts
21 08ce6f52 2021-04-29 op - location rules
22 b9231167 2021-02-08 op - event-based asynchronous I/O model
23 08ce6f52 2021-04-29 op - low memory footprint
24 b9220ca4 2021-01-11 op - small codebase, easily hackable
25 3e4749f7 2020-10-02 op
26 fab952e1 2020-10-03 op
27 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
28 286c4f40 2021-01-27 op
29 286c4f40 2021-01-27 op Even thought the current Gemini specification doesn't mention anything
30 601bc1cc 2021-01-30 op in this regard, I do think these are important things and so I tried
31 601bc1cc 2021-01-30 op to implement them in the most user-friendly way I could think of.
32 286c4f40 2021-01-27 op
33 601bc1cc 2021-01-30 op For starters, gmid has full support for IRI (RFC3987 —
34 22a742e4 2021-01-29 op Internationalized Resource Identifiers). IRIs are a superset of URIs,
35 286c4f40 2021-01-27 op so there aren't incompatibilities with URI-only clients.
36 286c4f40 2021-01-27 op
37 601bc1cc 2021-01-30 op There is full support also for punycode. In theory, the user doesn't
38 286c4f40 2021-01-27 op even need to know that punycode is a thing. The hostname in the
39 601bc1cc 2021-01-30 op configuration file can (and must be) in the decoded form (e.g. `naïve`
40 601bc1cc 2021-01-30 op and not `xn--nave-6pa`), gmid will do the rest.
41 286c4f40 2021-01-27 op
42 601bc1cc 2021-01-30 op The only missing piece is UNICODE normalisation of the IRI path: gmid
43 601bc1cc 2021-01-30 op doesn't do that (yet).
44 286c4f40 2021-01-27 op
45 286c4f40 2021-01-27 op
46 1487e11e 2021-02-06 op ## Configuration
47 1487e11e 2021-02-06 op
48 1487e11e 2021-02-06 op gmid has a rich configuration file, heavily inspired by OpenBSD'
49 08ce6f52 2021-04-29 op httpd, with every detail carefully documented in the manpage. Here's
50 08ce6f52 2021-04-29 op a minimal example of a config file:
51 1487e11e 2021-02-06 op
52 1487e11e 2021-02-06 op ```conf
53 08ce6f52 2021-04-29 op server "example.com" {
54 08ce6f52 2021-04-29 op cert "/path/to/cert.pem"
55 08ce6f52 2021-04-29 op key "/path/to/key.pem"
56 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
57 08ce6f52 2021-04-29 op }
58 08ce6f52 2021-04-29 op ```
59 08ce6f52 2021-04-29 op
60 3759d3eb 2021-07-06 op and a slightly more complex one
61 08ce6f52 2021-04-29 op
62 08ce6f52 2021-04-29 op ```conf
63 1487e11e 2021-02-06 op ipv6 on # enable ipv6
64 1487e11e 2021-02-06 op
65 3759d3eb 2021-07-06 op # define a macro
66 3759d3eb 2021-07-06 op cert_root = "/path/to/keys"
67 3759d3eb 2021-07-06 op
68 1487e11e 2021-02-06 op server "example.com" {
69 08ce6f52 2021-04-29 op alias "foobar.com"
70 1487e11e 2021-02-06 op
71 3759d3eb 2021-07-06 op cert $cert_root "/example.com.crt"
72 3759d3eb 2021-07-06 op key $cert_root "/example.com.pem"
73 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
74 1487e11e 2021-02-06 op
75 08ce6f52 2021-04-29 op # lang for text/gemini files
76 3759d3eb 2021-07-06 op lang "en"
77 08ce6f52 2021-04-29 op
78 08ce6f52 2021-04-29 op # only for locations that matches /files/*
79 08ce6f52 2021-04-29 op location "/files/*" {
80 08ce6f52 2021-04-29 op # generate directory listings
81 08ce6f52 2021-04-29 op auto index on
82 08ce6f52 2021-04-29 op }
83 08ce6f52 2021-04-29 op
84 08ce6f52 2021-04-29 op location "/repo/*" {
85 08ce6f52 2021-04-29 op # change the index file name
86 08ce6f52 2021-04-29 op index "README.gmi"
87 3759d3eb 2021-07-06 op lang "it"
88 08ce6f52 2021-04-29 op }
89 1487e11e 2021-02-06 op }
90 1487e11e 2021-02-06 op ```
91 1487e11e 2021-02-06 op
92 1487e11e 2021-02-06 op
93 b9220ca4 2021-01-11 op ## Building
94 3e4749f7 2020-10-02 op
95 4252e62c 2022-03-29 op gmid depends on libevent2, OpenSSL/LibreSSL and libtls (provided
96 4252e62c 2022-03-29 op either by LibreSSL or libretls). At build time, yacc (or GNU bison)
97 4252e62c 2022-03-29 op is also needed.
98 3e4749f7 2020-10-02 op
99 771d8f28 2021-01-17 op The build is as simple as
100 3e4749f7 2020-10-02 op
101 601bc1cc 2021-01-30 op ./configure
102 b9220ca4 2021-01-11 op make
103 3e4749f7 2020-10-02 op
104 2ddc9271 2021-03-29 op or `make static` to build a statically-linked executable.
105 2ddc9271 2021-03-29 op
106 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
107 f980545b 2021-01-21 op issue or notify me via email.
108 8f0da580 2021-01-21 op
109 771d8f28 2021-01-17 op To install execute:
110 881a9dd9 2021-01-16 op
111 771d8f28 2021-01-17 op make install
112 771d8f28 2021-01-17 op
113 bb4be662 2021-04-25 op Please keep in mind that the master branch, from time to time, may be
114 bb4be662 2021-04-25 op accidentally broken on some platforms. gmid is developed primarily on
115 bb4be662 2021-04-25 op OpenBSD/amd64 and commits on the master branch don't get always tested
116 bb4be662 2021-04-25 op in other OSes. Before tagging a release however, a comprehensive
117 c79b63f5 2021-04-27 op testing on various platform is done to ensure that everything is
118 c79b63f5 2021-04-27 op working as intended.
119 bb4be662 2021-04-25 op
120 bb4be662 2021-04-25 op
121 dd8cc7d3 2021-01-22 op ### Testing
122 dd8cc7d3 2021-01-22 op
123 31a4993a 2021-01-23 op Execute
124 dd8cc7d3 2021-01-22 op
125 dd8cc7d3 2021-01-22 op make regress
126 dd8cc7d3 2021-01-22 op
127 ed78e81b 2022-02-18 op to start the suite. Keep in mind that the regression tests needs to
128 601bc1cc 2021-01-30 op create files inside the `regress` directory and bind the 10965 port.
129 dd8cc7d3 2021-01-22 op
130 dd8cc7d3 2021-01-22 op
131 456a4c6b 2022-03-29 op ## Contributing
132 456a4c6b 2022-03-29 op
133 456a4c6b 2022-03-29 op Any form of contribution is welcome, not only patches or bug reports.
134 456a4c6b 2022-03-29 op If you have a sample configuration for some specific use-case, a
135 456a4c6b 2022-03-29 op script or anything that could be useful to others, consider adding it
136 456a4c6b 2022-03-29 op to the `contrib` directory.
137 456a4c6b 2022-03-29 op
138 456a4c6b 2022-03-29 op
139 881a9dd9 2021-01-16 op ## Architecture/Security considerations
140 881a9dd9 2021-01-16 op
141 d29a2ee2 2022-09-06 op **outdated: revisit for gmid 2.0**
142 d29a2ee2 2022-09-06 op
143 d29a2ee2 2022-09-06 op
144 290b5baa 2021-02-23 op gmid is composed by four processes: the parent process, the logger,
145 290b5baa 2021-02-23 op the listener and the executor. The parent process is the only one
146 290b5baa 2021-02-23 op that doesn't drop privileges, but all it does is to wait for a SIGHUP
147 290b5baa 2021-02-23 op to reload the configuration and spawn a new generation of children
148 e58a447a 2021-07-29 op process. The logger process gathers the logs and prints 'em to
149 290b5baa 2021-02-23 op stderr or syslog (for the time being.) The listener process is the
150 290b5baa 2021-02-23 op only one that needs internet access and is sandboxed by default. The
151 be52e954 2021-07-09 op executor process exists only to fork and execute CGI scripts, and
152 be52e954 2021-07-09 op optionally to connect to FastCGI applications.
153 881a9dd9 2021-01-16 op
154 dcfdb969 2021-10-24 op On OpenBSD the processes are all `pledge(2)`d and `unveil(2)`ed.
155 881a9dd9 2021-01-16 op
156 94be0bf0 2021-03-20 op On FreeBSD, the listener and logger process are sandboxed with `capsicum(4)`.
157 d939d0f0 2021-01-17 op
158 601bc1cc 2021-01-30 op On Linux, a `seccomp(2)` filter is installed in the listener to allow
159 601bc1cc 2021-01-30 op only certain syscalls, see [sandbox.c](sandbox.c) for more information
160 67c49bc5 2021-09-19 op about the BPF program. If available, landlock is used to limit the
161 67c49bc5 2021-09-19 op portion of the file system gmid can access (requires linux 5.13+.)
162 ea58dab1 2021-01-17 op
163 6957a8c2 2021-06-04 op In any case, it's advisable to run gmid inside some sort of
164 0b00962d 2021-01-25 op container/jail/chroot.