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