Blob


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]: https://man.openbsd.org/httpd.8
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 # /etc/gmid.conf
46 server "example.com" {
47 listen on * port 1965
48 cert "/path/to/cert.pem"
49 key "/path/to/key.pem"
50 root "/var/gemini/example.com"
51 }
52 ```
54 and a slightly more complex one
56 ```conf
57 # /etc/gmid.conf
58 cert_root = "/path/to/keys"
60 server "example.com" {
61 listen on * port 1965
63 alias "foobar.com"
65 cert $cert_root "/example.com.crt"
66 key $cert_root "/example.com.pem"
67 root "/var/gemini/example.com"
69 # lang for text/gemini files
70 lang "en"
72 # only for locations that matches /files/*
73 location "/files/*" {
74 # generate directory listings
75 auto index on
76 }
78 location "/repo/*" {
79 # change the index file name
80 index "README.gmi"
81 lang "it"
82 }
83 }
84 ```
87 ## Building
89 gmid depends on libevent2, LibreSSL or OpenSSL, and yacc or GNU bison.
91 The build is as simple as
93 $ ./configure
94 $ make
96 If the configure scripts fails to pick up something, please open an
97 issue or notify me via email.
99 To install execute:
101 # make install
103 Please keep in mind that the master branch, from time to time, may be
104 accidentally broken on some platforms. gmid is developed primarily on
105 OpenBSD/amd64 and commits on the master branch don't get always tested
106 in other OSes. Before tagging a release however, a comprehensive
107 testing on various platform is done to ensure that everything is
108 working as intended.
111 ### Testing
113 Execute
115 $ make regress
117 to start the suite. Keep in mind that the regression tests needs to
118 create a few file inside the `regress` directory and bind the 10965
119 port.
122 ## Contributing
124 Any form of contribution is welcome, not only patches or bug reports.
125 If you have a sample configuration for some specific use-case, a
126 script or anything that could be useful to others, consider adding it
127 to the `contrib` directory.
130 ## Architecture/Security considerations
132 The internal architecture was revisited for the 2.0 release. For
133 earlier releases, please refer to previous revision of this file.
135 gmid has a privsep design, where the operations done by the daemon are
136 splitted into multiple processes:
138 - main: the main process is the only one that keeps the original
139 privileges. It opens the TLS certificates on the behalf of the
140 `server` and `crypto` processes, reloads the configuration upon
141 `SIGHUP` and re-opens the log files upon `SIGUSR1`.
143 - logger: handles the logging with syslog and/or local files.
145 - server: listens for connections and serves the request. It also
146 speaks FastCGI and do the proxying.
148 - crypto: holds the TLS private keys to avoid a compromised `server`
149 process to disclose them.