1 # gmid
2 
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.
6 
7 A few helper programs are shipped as part of gmid:
8 
9  - `gg` is a simple command-line Gemini client.
10 
11  - `gemexp` is a stripped-down config-less version of gmid to quickly
12    serve a directory from the command line.
13 
14  - `titan` is a command-line titan client.
15 
16 
17 ## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
18 
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.
22 
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.
26 
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.
31 
32 The only missing piece is UNICODE normalisation of the IRI path: gmid
33 doesn't do that (yet).
34 
35 
36 ## Configuration
37 
38 [httpd]: https://man.openbsd.org/httpd.8
39 
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:
43 
44 ```conf
45 server "example.com" {
46 	listen on * port 1965
47 	cert "/path/to/cert.pem"
48 	key  "/path/to/key.pem"
49 	root "/var/gemini/example.com"
50 }
51 ```
52 
53 and a slightly more complex one
54 
55 ```conf
56 cert_root = "/path/to/keys"
57 
58 server "example.com" {
59 	listen on * port 1965
60 
61 	alias "foobar.com"
62 
63 	cert $cert_root "/example.com.crt"
64 	key  $cert_root "/example.com.pem"
65 	root "/var/gemini/example.com"
66 
67 	# lang for text/gemini files
68 	lang "en"
69 
70 	# only for locations that matches /files/*
71 	location "/files/*" {
72 		# generate directory listings
73 		auto index on
74 	}
75 
76 	location "/repo/*" {
77 		# change the index file name
78 		index "README.gmi"
79 		lang "it"
80 	}
81 }
82 ```
83 
84 
85 ## Building
86 
87 gmid depends on libevent2, OpenSSL/LibreSSL and libtls (provided
88 either by LibreSSL or libretls).  At build time, yacc (or GNU bison)
89 is also needed.
90 
91 The build is as simple as
92 
93 	$ ./configure
94 	$ make
95 
96 If the configure scripts fails to pick up something, please open an
97 issue or notify me via email.
98 
99 To install execute:
100 
101 	# make install
102 
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.
109 
110 
111 ### Testing
112 
113 Execute
114 
115 	$ make regress
116 
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.
120 
121 
122 ## Contributing
123 
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.
128 
129 
130 ## Architecture/Security considerations
131 
132 The internal architecture was revisited for the 2.0 release.  For
133 previous releases, please refer to previous revision of this file.
134 
135 gmid has a privsep design, where the operations done by the daemon are
136 splitted into multiple processes:
137 
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 and reloads the configuration upon
141    `SIGHUP`.
142 
143  - logger: handles the logging with syslog and/or local files.
144 
145  - server: listen on the binded ports and serves the request.  This
146    also include speaking FastCGI and proxying requests.
147 
148  - crypto: holds the TLS private keys to avoid a compromised `server`
149    process to disclose them.