4 fea6a856 2023-06-24 op > The `master` branch is WIP: it's what gmid 2.0 will be, with
5 fea6a856 2023-06-24 op > breaking changes et al. Please use the latest release from the 1.8
6 23f0ac49 2023-06-24 op > branch for a stable and documented experience, thank you.
8 fea6a856 2023-06-24 op gmid is a full-featured Gemini server written with security in mind.
9 fea6a856 2023-06-24 op It can serve static files, has optional FastCGI and proxying support,
10 fea6a856 2023-06-24 op and a rich configuration syntax.
12 6a60134c 2023-06-24 op gg is a simple command-line Gemini client, and ge a stripped-down
13 6a60134c 2023-06-24 op config-less gmid version used to quickly serve a directory locally
17 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
19 286c4f40 2021-01-27 op Even thought the current Gemini specification doesn't mention anything
20 601bc1cc 2021-01-30 op in this regard, I do think these are important things and so I tried
21 601bc1cc 2021-01-30 op to implement them in the most user-friendly way I could think of.
23 601bc1cc 2021-01-30 op For starters, gmid has full support for IRI (RFC3987 —
24 22a742e4 2021-01-29 op Internationalized Resource Identifiers). IRIs are a superset of URIs,
25 286c4f40 2021-01-27 op so there aren't incompatibilities with URI-only clients.
27 601bc1cc 2021-01-30 op There is full support also for punycode. In theory, the user doesn't
28 286c4f40 2021-01-27 op even need to know that punycode is a thing. The hostname in the
29 601bc1cc 2021-01-30 op configuration file can (and must be) in the decoded form (e.g. `naïve`
30 601bc1cc 2021-01-30 op and not `xn--nave-6pa`), gmid will do the rest.
32 601bc1cc 2021-01-30 op The only missing piece is UNICODE normalisation of the IRI path: gmid
33 601bc1cc 2021-01-30 op doesn't do that (yet).
36 1487e11e 2021-02-06 op ## Configuration
38 fea6a856 2023-06-24 op [httpd]: https://man.openbsd.org/httpd.8
40 1487e11e 2021-02-06 op gmid has a rich configuration file, heavily inspired by OpenBSD'
41 fea6a856 2023-06-24 op [httpd(8)][httpd], with every detail carefully documented in the
42 fea6a856 2023-06-24 op manpage. Here's a minimal example of a config file:
45 08ce6f52 2021-04-29 op server "example.com" {
46 fea6a856 2023-06-24 op listen on * port 1965
47 08ce6f52 2021-04-29 op cert "/path/to/cert.pem"
48 08ce6f52 2021-04-29 op key "/path/to/key.pem"
49 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
53 3759d3eb 2021-07-06 op and a slightly more complex one
56 3759d3eb 2021-07-06 op cert_root = "/path/to/keys"
58 1487e11e 2021-02-06 op server "example.com" {
59 fea6a856 2023-06-24 op listen on * port 1965
61 08ce6f52 2021-04-29 op alias "foobar.com"
63 3759d3eb 2021-07-06 op cert $cert_root "/example.com.crt"
64 3759d3eb 2021-07-06 op key $cert_root "/example.com.pem"
65 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
67 08ce6f52 2021-04-29 op # lang for text/gemini files
70 08ce6f52 2021-04-29 op # only for locations that matches /files/*
71 08ce6f52 2021-04-29 op location "/files/*" {
72 08ce6f52 2021-04-29 op # generate directory listings
76 08ce6f52 2021-04-29 op location "/repo/*" {
77 08ce6f52 2021-04-29 op # change the index file name
78 08ce6f52 2021-04-29 op index "README.gmi"
87 4252e62c 2022-03-29 op gmid depends on libevent2, OpenSSL/LibreSSL and libtls (provided
88 4252e62c 2022-03-29 op either by LibreSSL or libretls). At build time, yacc (or GNU bison)
89 4252e62c 2022-03-29 op is also needed.
91 771d8f28 2021-01-17 op The build is as simple as
96 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
97 f980545b 2021-01-21 op issue or notify me via email.
99 771d8f28 2021-01-17 op To install execute:
101 fea6a856 2023-06-24 op # make install
103 bb4be662 2021-04-25 op Please keep in mind that the master branch, from time to time, may be
104 bb4be662 2021-04-25 op accidentally broken on some platforms. gmid is developed primarily on
105 bb4be662 2021-04-25 op OpenBSD/amd64 and commits on the master branch don't get always tested
106 bb4be662 2021-04-25 op in other OSes. Before tagging a release however, a comprehensive
107 c79b63f5 2021-04-27 op testing on various platform is done to ensure that everything is
108 c79b63f5 2021-04-27 op working as intended.
115 fea6a856 2023-06-24 op $ make regress
117 ed78e81b 2022-02-18 op to start the suite. Keep in mind that the regression tests needs to
118 fea6a856 2023-06-24 op create a few file inside the `regress` directory and bind the 10965
122 456a4c6b 2022-03-29 op ## Contributing
124 456a4c6b 2022-03-29 op Any form of contribution is welcome, not only patches or bug reports.
125 456a4c6b 2022-03-29 op If you have a sample configuration for some specific use-case, a
126 456a4c6b 2022-03-29 op script or anything that could be useful to others, consider adding it
127 456a4c6b 2022-03-29 op to the `contrib` directory.
130 881a9dd9 2021-01-16 op ## Architecture/Security considerations
132 fea6a856 2023-06-24 op The internal architecture was revisited for the 2.0 release. For
133 fea6a856 2023-06-24 op previous releases, please refer to previous revision of this file.
135 fea6a856 2023-06-24 op gmid has a privsep design, where the operations done by the daemon are
136 fea6a856 2023-06-24 op splitted into multiple processes:
138 fea6a856 2023-06-24 op - main: the main process is the only one that keeps the original
139 fea6a856 2023-06-24 op privileges. It opens the TLS certificates on the behalf of the
140 fea6a856 2023-06-24 op `server` and `crypto` processes and reloads the configuration upon
143 fea6a856 2023-06-24 op - logger: logs the requests.
145 2b0b2661 2023-07-01 op - server: listen on the binded ports and serves the request. This
146 2b0b2661 2023-07-01 op also include speaking FastCGI and proxying requests.
148 fea6a856 2023-06-24 op - crypto: (used only on OpenBSD at the time of writing.) Holds the
149 fea6a856 2023-06-24 op TLS private keys to avoid a compromised `server` process to
150 fea6a856 2023-06-24 op disclose them.
