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 fdb4572d 2023-07-25 op A few helper programs are shipped as part of gmid:
14 fdb4572d 2023-07-25 op - `gg` is a simple command-line Gemini client.
16 fdb4572d 2023-07-25 op - `gemexp` is a stripped-down config-less version of gmid to quickly
17 fdb4572d 2023-07-25 op serve a directory from the command line.
19 fdb4572d 2023-07-25 op - `titan` is a command-line titan client.
22 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
24 286c4f40 2021-01-27 op Even thought the current Gemini specification doesn't mention anything
25 601bc1cc 2021-01-30 op in this regard, I do think these are important things and so I tried
26 601bc1cc 2021-01-30 op to implement them in the most user-friendly way I could think of.
28 601bc1cc 2021-01-30 op For starters, gmid has full support for IRI (RFC3987 —
29 22a742e4 2021-01-29 op Internationalized Resource Identifiers). IRIs are a superset of URIs,
30 286c4f40 2021-01-27 op so there aren't incompatibilities with URI-only clients.
32 601bc1cc 2021-01-30 op There is full support also for punycode. In theory, the user doesn't
33 286c4f40 2021-01-27 op even need to know that punycode is a thing. The hostname in the
34 601bc1cc 2021-01-30 op configuration file can (and must be) in the decoded form (e.g. `naïve`
35 601bc1cc 2021-01-30 op and not `xn--nave-6pa`), gmid will do the rest.
37 601bc1cc 2021-01-30 op The only missing piece is UNICODE normalisation of the IRI path: gmid
38 601bc1cc 2021-01-30 op doesn't do that (yet).
41 1487e11e 2021-02-06 op ## Configuration
43 fea6a856 2023-06-24 op [httpd]: https://man.openbsd.org/httpd.8
45 1487e11e 2021-02-06 op gmid has a rich configuration file, heavily inspired by OpenBSD'
46 fea6a856 2023-06-24 op [httpd(8)][httpd], with every detail carefully documented in the
47 fea6a856 2023-06-24 op manpage. Here's a minimal example of a config file:
50 08ce6f52 2021-04-29 op server "example.com" {
51 fea6a856 2023-06-24 op listen on * port 1965
52 08ce6f52 2021-04-29 op cert "/path/to/cert.pem"
53 08ce6f52 2021-04-29 op key "/path/to/key.pem"
54 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
58 3759d3eb 2021-07-06 op and a slightly more complex one
61 3759d3eb 2021-07-06 op cert_root = "/path/to/keys"
63 1487e11e 2021-02-06 op server "example.com" {
64 fea6a856 2023-06-24 op listen on * port 1965
66 08ce6f52 2021-04-29 op alias "foobar.com"
68 3759d3eb 2021-07-06 op cert $cert_root "/example.com.crt"
69 3759d3eb 2021-07-06 op key $cert_root "/example.com.pem"
70 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
72 08ce6f52 2021-04-29 op # lang for text/gemini files
75 08ce6f52 2021-04-29 op # only for locations that matches /files/*
76 08ce6f52 2021-04-29 op location "/files/*" {
77 08ce6f52 2021-04-29 op # generate directory listings
81 08ce6f52 2021-04-29 op location "/repo/*" {
82 08ce6f52 2021-04-29 op # change the index file name
83 08ce6f52 2021-04-29 op index "README.gmi"
92 4252e62c 2022-03-29 op gmid depends on libevent2, OpenSSL/LibreSSL and libtls (provided
93 4252e62c 2022-03-29 op either by LibreSSL or libretls). At build time, yacc (or GNU bison)
94 4252e62c 2022-03-29 op is also needed.
96 771d8f28 2021-01-17 op The build is as simple as
101 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
102 f980545b 2021-01-21 op issue or notify me via email.
104 771d8f28 2021-01-17 op To install execute:
106 fea6a856 2023-06-24 op # make install
108 bb4be662 2021-04-25 op Please keep in mind that the master branch, from time to time, may be
109 bb4be662 2021-04-25 op accidentally broken on some platforms. gmid is developed primarily on
110 bb4be662 2021-04-25 op OpenBSD/amd64 and commits on the master branch don't get always tested
111 bb4be662 2021-04-25 op in other OSes. Before tagging a release however, a comprehensive
112 c79b63f5 2021-04-27 op testing on various platform is done to ensure that everything is
113 c79b63f5 2021-04-27 op working as intended.
120 fea6a856 2023-06-24 op $ make regress
122 ed78e81b 2022-02-18 op to start the suite. Keep in mind that the regression tests needs to
123 fea6a856 2023-06-24 op create a few file inside the `regress` directory and bind the 10965
127 456a4c6b 2022-03-29 op ## Contributing
129 456a4c6b 2022-03-29 op Any form of contribution is welcome, not only patches or bug reports.
130 456a4c6b 2022-03-29 op If you have a sample configuration for some specific use-case, a
131 456a4c6b 2022-03-29 op script or anything that could be useful to others, consider adding it
132 456a4c6b 2022-03-29 op to the `contrib` directory.
135 881a9dd9 2021-01-16 op ## Architecture/Security considerations
137 fea6a856 2023-06-24 op The internal architecture was revisited for the 2.0 release. For
138 fea6a856 2023-06-24 op previous releases, please refer to previous revision of this file.
140 fea6a856 2023-06-24 op gmid has a privsep design, where the operations done by the daemon are
141 fea6a856 2023-06-24 op splitted into multiple processes:
143 fea6a856 2023-06-24 op - main: the main process is the only one that keeps the original
144 fea6a856 2023-06-24 op privileges. It opens the TLS certificates on the behalf of the
145 fea6a856 2023-06-24 op `server` and `crypto` processes and reloads the configuration upon
148 4f97572e 2023-08-23 op - logger: handles the logging with syslog and/or local files.
150 2b0b2661 2023-07-01 op - server: listen on the binded ports and serves the request. This
151 2b0b2661 2023-07-01 op also include speaking FastCGI and proxying requests.
153 4f97572e 2023-08-23 op - crypto: holds the TLS private keys to avoid a compromised `server`
154 4f97572e 2023-08-23 op process to disclose them.
