3 fea6a856 2023-06-24 op gmid is a full-featured Gemini server written with security in mind.
4 fea6a856 2023-06-24 op It can serve static files, has optional FastCGI and proxying support,
5 fea6a856 2023-06-24 op and a rich configuration syntax.
7 fdb4572d 2023-07-25 op A few helper programs are shipped as part of gmid:
9 fdb4572d 2023-07-25 op - `gg` is a simple command-line Gemini client.
11 fdb4572d 2023-07-25 op - `gemexp` is a stripped-down config-less version of gmid to quickly
12 fdb4572d 2023-07-25 op serve a directory from the command line.
14 fdb4572d 2023-07-25 op - `titan` is a command-line titan client.
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 3b9388d8 2024-01-11 op gmid depends on libevent2, LibreSSL or OpenSSL, and yacc or GNU bison.
89 771d8f28 2021-01-17 op The build is as simple as
94 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
95 f980545b 2021-01-21 op issue or notify me via email.
97 771d8f28 2021-01-17 op To install execute:
99 fea6a856 2023-06-24 op # make install
101 bb4be662 2021-04-25 op Please keep in mind that the master branch, from time to time, may be
102 bb4be662 2021-04-25 op accidentally broken on some platforms. gmid is developed primarily on
103 bb4be662 2021-04-25 op OpenBSD/amd64 and commits on the master branch don't get always tested
104 bb4be662 2021-04-25 op in other OSes. Before tagging a release however, a comprehensive
105 c79b63f5 2021-04-27 op testing on various platform is done to ensure that everything is
106 c79b63f5 2021-04-27 op working as intended.
113 fea6a856 2023-06-24 op $ make regress
115 ed78e81b 2022-02-18 op to start the suite. Keep in mind that the regression tests needs to
116 fea6a856 2023-06-24 op create a few file inside the `regress` directory and bind the 10965
120 456a4c6b 2022-03-29 op ## Contributing
122 456a4c6b 2022-03-29 op Any form of contribution is welcome, not only patches or bug reports.
123 456a4c6b 2022-03-29 op If you have a sample configuration for some specific use-case, a
124 456a4c6b 2022-03-29 op script or anything that could be useful to others, consider adding it
125 456a4c6b 2022-03-29 op to the `contrib` directory.
128 881a9dd9 2021-01-16 op ## Architecture/Security considerations
130 fea6a856 2023-06-24 op The internal architecture was revisited for the 2.0 release. For
131 84285be9 2024-01-11 op earlier releases, please refer to previous revision of this file.
133 fea6a856 2023-06-24 op gmid has a privsep design, where the operations done by the daemon are
134 fea6a856 2023-06-24 op splitted into multiple processes:
136 fea6a856 2023-06-24 op - main: the main process is the only one that keeps the original
137 fea6a856 2023-06-24 op privileges. It opens the TLS certificates on the behalf of the
138 13f90009 2024-01-11 op `server` and `crypto` processes, reloads the configuration upon
139 13f90009 2024-01-11 op `SIGHUP` and re-opens the log files upon `SIGUSR1`.
141 4f97572e 2023-08-23 op - logger: handles the logging with syslog and/or local files.
143 13f90009 2024-01-11 op - server: listens for connections and serves the request. It also
144 13f90009 2024-01-11 op speaks FastCGI and do the proxying.
146 4f97572e 2023-08-23 op - crypto: holds the TLS private keys to avoid a compromised `server`
147 4f97572e 2023-08-23 op process to disclose them.
