1 # gmid
3 gmid is a full-featured Gemini server written with security in mind.
4 It can serve static files, has optional FastCGI and proxying support,
5 and a rich configuration syntax.
7 A few helper programs are shipped as part of gmid:
9 - `gg` is a simple command-line Gemini client.
11 - `gemexp` is a stripped-down config-less version of gmid to quickly
12 serve a directory from the command line.
14 - `titan` is a command-line titan client.
17 ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
19 Even thought the current Gemini specification doesn't mention anything
20 in this regard, I do think these are important things and so I tried
21 to implement them in the most user-friendly way I could think of.
23 For starters, gmid has full support for IRI (RFC3987 —
24 Internationalized Resource Identifiers). IRIs are a superset of URIs,
25 so there aren't incompatibilities with URI-only clients.
27 There is full support also for punycode. In theory, the user doesn't
28 even need to know that punycode is a thing. The hostname in the
29 configuration file can (and must be) in the decoded form (e.g. `naïve`
30 and not `xn--nave-6pa`), gmid will do the rest.
32 The only missing piece is UNICODE normalisation of the IRI path: gmid
33 doesn't do that (yet).
36 ## Configuration
38 [httpd]:
40 gmid has a rich configuration file, heavily inspired by OpenBSD'
41 [httpd(8)][httpd], with every detail carefully documented in the
42 manpage. Here's a minimal example of a config file:
44 ```conf
45 server "" {
46 listen on * port 1965
47 cert "/path/to/cert.pem"
48 key "/path/to/key.pem"
49 root "/var/gemini/"
50 }
51 ```
53 and a slightly more complex one
55 ```conf
56 cert_root = "/path/to/keys"
58 server "" {
59 listen on * port 1965
61 alias ""
63 cert $cert_root "/"
64 key $cert_root "/"
65 root "/var/gemini/"
67 # lang for text/gemini files
68 lang "en"
70 # only for locations that matches /files/*
71 location "/files/*" {
72 # generate directory listings
73 auto index on
74 }
76 location "/repo/*" {
77 # change the index file name
78 index "README.gmi"
79 lang "it"
80 }
81 }
82 ```
85 ## Building
87 gmid depends on libevent2, LibreSSL or OpenSSL, and yacc or GNU bison.
89 The build is as simple as
91 $ ./configure
92 $ make
94 If the configure scripts fails to pick up something, please open an
95 issue or notify me via email.
97 To install execute:
99 # make install
101 Please keep in mind that the master branch, from time to time, may be
102 accidentally broken on some platforms. gmid is developed primarily on
103 OpenBSD/amd64 and commits on the master branch don't get always tested
104 in other OSes. Before tagging a release however, a comprehensive
105 testing on various platform is done to ensure that everything is
106 working as intended.
109 ### Testing
111 Execute
113 $ make regress
115 to start the suite. Keep in mind that the regression tests needs to
116 create a few file inside the `regress` directory and bind the 10965
117 port.
120 ## Contributing
122 Any form of contribution is welcome, not only patches or bug reports.
123 If you have a sample configuration for some specific use-case, a
124 script or anything that could be useful to others, consider adding it
125 to the `contrib` directory.
128 ## Architecture/Security considerations
130 The internal architecture was revisited for the 2.0 release. For
131 earlier releases, please refer to previous revision of this file.
133 gmid has a privsep design, where the operations done by the daemon are
134 splitted into multiple processes:
136 - main: the main process is the only one that keeps the original
137 privileges. It opens the TLS certificates on the behalf of the
138 `server` and `crypto` processes, reloads the configuration upon
139 `SIGHUP` and re-opens the log files upon `SIGUSR1`.
141 - logger: handles the logging with syslog and/or local files.
143 - server: listens for connections and serves the request. It also
144 speaks FastCGI and do the proxying.
146 - crypto: holds the TLS private keys to avoid a compromised `server`
147 process to disclose them.