Blame


1 b9220ca4 2021-01-11 op # gmid
2 3e4749f7 2020-10-02 op
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.
6 3e4749f7 2020-10-02 op
7 fdb4572d 2023-07-25 op A few helper programs are shipped as part of gmid:
8 3e4749f7 2020-10-02 op
9 fdb4572d 2023-07-25 op - `gg` is a simple command-line Gemini client.
10 6a60134c 2023-06-24 op
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.
13 fdb4572d 2023-07-25 op
14 fdb4572d 2023-07-25 op - `titan` is a command-line titan client.
15 fdb4572d 2023-07-25 op
16 fdb4572d 2023-07-25 op
17 286c4f40 2021-01-27 op ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
18 286c4f40 2021-01-27 op
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.
22 286c4f40 2021-01-27 op
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.
26 286c4f40 2021-01-27 op
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.
31 286c4f40 2021-01-27 op
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).
34 286c4f40 2021-01-27 op
35 286c4f40 2021-01-27 op
36 1487e11e 2021-02-06 op ## Configuration
37 1487e11e 2021-02-06 op
38 fea6a856 2023-06-24 op [httpd]: https://man.openbsd.org/httpd.8
39 fea6a856 2023-06-24 op
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:
43 1487e11e 2021-02-06 op
44 1487e11e 2021-02-06 op ```conf
45 b9839671 2024-06-28 op # /etc/gmid.conf
46 08ce6f52 2021-04-29 op server "example.com" {
47 fea6a856 2023-06-24 op listen on * port 1965
48 08ce6f52 2021-04-29 op cert "/path/to/cert.pem"
49 08ce6f52 2021-04-29 op key "/path/to/key.pem"
50 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
51 08ce6f52 2021-04-29 op }
52 08ce6f52 2021-04-29 op ```
53 08ce6f52 2021-04-29 op
54 3759d3eb 2021-07-06 op and a slightly more complex one
55 08ce6f52 2021-04-29 op
56 08ce6f52 2021-04-29 op ```conf
57 b9839671 2024-06-28 op # /etc/gmid.conf
58 3759d3eb 2021-07-06 op cert_root = "/path/to/keys"
59 3759d3eb 2021-07-06 op
60 1487e11e 2021-02-06 op server "example.com" {
61 fea6a856 2023-06-24 op listen on * port 1965
62 fea6a856 2023-06-24 op
63 08ce6f52 2021-04-29 op alias "foobar.com"
64 1487e11e 2021-02-06 op
65 3759d3eb 2021-07-06 op cert $cert_root "/example.com.crt"
66 3759d3eb 2021-07-06 op key $cert_root "/example.com.pem"
67 08ce6f52 2021-04-29 op root "/var/gemini/example.com"
68 1487e11e 2021-02-06 op
69 08ce6f52 2021-04-29 op # lang for text/gemini files
70 3759d3eb 2021-07-06 op lang "en"
71 08ce6f52 2021-04-29 op
72 08ce6f52 2021-04-29 op # only for locations that matches /files/*
73 08ce6f52 2021-04-29 op location "/files/*" {
74 08ce6f52 2021-04-29 op # generate directory listings
75 08ce6f52 2021-04-29 op auto index on
76 08ce6f52 2021-04-29 op }
77 08ce6f52 2021-04-29 op
78 08ce6f52 2021-04-29 op location "/repo/*" {
79 08ce6f52 2021-04-29 op # change the index file name
80 08ce6f52 2021-04-29 op index "README.gmi"
81 3759d3eb 2021-07-06 op lang "it"
82 08ce6f52 2021-04-29 op }
83 1487e11e 2021-02-06 op }
84 1487e11e 2021-02-06 op ```
85 1487e11e 2021-02-06 op
86 1487e11e 2021-02-06 op
87 b9220ca4 2021-01-11 op ## Building
88 3e4749f7 2020-10-02 op
89 3b9388d8 2024-01-11 op gmid depends on libevent2, LibreSSL or OpenSSL, and yacc or GNU bison.
90 3e4749f7 2020-10-02 op
91 771d8f28 2021-01-17 op The build is as simple as
92 3e4749f7 2020-10-02 op
93 fea6a856 2023-06-24 op $ ./configure
94 fea6a856 2023-06-24 op $ make
95 3e4749f7 2020-10-02 op
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.
98 8f0da580 2021-01-21 op
99 771d8f28 2021-01-17 op To install execute:
100 881a9dd9 2021-01-16 op
101 fea6a856 2023-06-24 op # make install
102 771d8f28 2021-01-17 op
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.
109 bb4be662 2021-04-25 op
110 bb4be662 2021-04-25 op
111 dd8cc7d3 2021-01-22 op ### Testing
112 dd8cc7d3 2021-01-22 op
113 31a4993a 2021-01-23 op Execute
114 dd8cc7d3 2021-01-22 op
115 fea6a856 2023-06-24 op $ make regress
116 dd8cc7d3 2021-01-22 op
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
119 fea6a856 2023-06-24 op port.
120 dd8cc7d3 2021-01-22 op
121 dd8cc7d3 2021-01-22 op
122 456a4c6b 2022-03-29 op ## Contributing
123 456a4c6b 2022-03-29 op
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.
128 456a4c6b 2022-03-29 op
129 456a4c6b 2022-03-29 op
130 881a9dd9 2021-01-16 op ## Architecture/Security considerations
131 881a9dd9 2021-01-16 op
132 fea6a856 2023-06-24 op The internal architecture was revisited for the 2.0 release. For
133 84285be9 2024-01-11 op earlier releases, please refer to previous revision of this file.
134 d29a2ee2 2022-09-06 op
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:
137 d29a2ee2 2022-09-06 op
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 13f90009 2024-01-11 op `server` and `crypto` processes, reloads the configuration upon
141 13f90009 2024-01-11 op `SIGHUP` and re-opens the log files upon `SIGUSR1`.
142 881a9dd9 2021-01-16 op
143 4f97572e 2023-08-23 op - logger: handles the logging with syslog and/or local files.
144 881a9dd9 2021-01-16 op
145 13f90009 2024-01-11 op - server: listens for connections and serves the request. It also
146 13f90009 2024-01-11 op speaks FastCGI and do the proxying.
147 d939d0f0 2021-01-17 op
148 4f97572e 2023-08-23 op - crypto: holds the TLS private keys to avoid a compromised `server`
149 4f97572e 2023-08-23 op process to disclose them.