Blob


1 .\" Copyright (c) 2022 Omar Polo <op@omarpolo.com>
2 .\"
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
6 .\"
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .Dd September 8, 2022
15 .Dt GMID.CONF 5
16 .Os
17 .Sh NAME
18 .Nm gmid.conf
19 .Nd gmid Gemini server configuration file
20 .Sh DESCRIPTION
21 .Nm
22 is the configuration file format for the
23 .Xr gmid 8
24 Gemini server.
25 .Pp
26 The configuration file is divided into three sections:
27 .Bl -tag -width xxxx
28 .It Sy Macros
29 User-defined variables may be defined and used later, simplifying the
30 configuration file.
31 .It Sy Global Options
32 Global settings for
33 .Nm .
34 .It Sy Servers
35 Virtual hosts definition.
36 .It Sy Types
37 Media types and extensions.
38 .El
39 .Pp
40 Within the sections, empty lines are ignored and comments can be put
41 anywhere in the file using a hash mark
42 .Pq Sq # ,
43 and extend to the end of the current line.
44 A boolean is either the symbol
45 .Sq on
46 or
47 .Sq off .
48 A string is a sequence of characters wrapped in double quotes,
49 .Dq like this .
50 Multiple strings one next to the other are joined into a single
51 string:
52 .Bd -literal -offset indent
53 # equivalent to "temporary-failure"
54 block return 40 "temporary" "-" "failure"
55 .Ed
56 .Pp
57 Furthermore, quoting is necessary only when a string needs to contain
58 special characters
59 .Pq like spaces or punctuation ,
60 something that looks like a number or a reserved keyword.
61 The last example could have been written also as:
62 .Bd -literal -offset indent
63 block return 40 temporary "-" failure
64 .Ed
65 .Pp
66 Strict ordering of the sections is not enforced, so that is possible
67 to mix macros, options and
68 .Ic server
69 blocks.
70 However, defining all the
71 .Ic server
72 blocks after the macros and the global options is recommended.
73 .Pp
74 Newlines are often optional, except around top-level instructions, and
75 semicolons
76 .Dq \&;
77 can also be optionally used to separate options.
78 .Pp
79 Additional configuration files can be included with the
80 .Ic include
81 keyword, for example:
82 .Bd -literal -offset indent
83 include "/etc/gmid.conf.local"
84 .Ed
85 .Ss Macros
86 Macros can be defined that will later be expanded in context.
87 Macro names must start with a letter, digit or underscore and may
88 contain any of those characters.
89 Macros names may not be reserved words.
90 Macros are not expanded inside quotes.
91 .Pp
92 Two kinds of macros are supported: variable-like and proper macros.
93 When a macro is invoked with a
94 .Dq $
95 before its name its expanded as a string, whereas when it's invoked
96 with a
97 .Dq @
98 its expanded in-place.
99 .Pp
100 For example:
101 .Bd -literal -offset indent
102 dir = "/var/gemini"
103 certdir = "/etc/keys"
104 common = "lang it; auto index on"
106 server "foo" {
107 root $dir "/foo" # -> /var/gemini/foo
108 cert $certdir "/foo.pem" # -> /etc/keys/foo.pem
109 key $certdir "/foo.key" # -> /etc/keys/foo.key
110 @common
112 .Ed
113 .Ss Global Options
114 .Bl -tag -width 12m
115 .It Ic chroot Ar path
116 .Xr chroot 2
117 the process to the given
118 .Ar path .
119 The daemon has to be run with root privileges and thus the option
120 .Ic user
121 needs to be provided, so privileges can be dropped.
122 Note that
123 .Nm
124 will enter the chroot after loading the TLS keys, but before opening
125 the virtual host root directories.
126 It's recommended to keep the TLS keys outside the chroot.
127 Future version of
128 .Nm
129 may enforce this.
130 .It Ic ipv6 Ar bool
131 Enable or disable IPv6 support, off by default.
132 .It Ic port Ar portno
133 The port to listen on.
134 1965 by default.
135 .It Ic prefork Ar number
136 Run the specified number of server processes.
137 This increases the performance and prevents delays when connecting to
138 a server.
139 When not in config-less mode,
140 .Nm
141 runs 3 server processes by default.
142 The maximum number allowed is 16.
143 .It Ic protocols Ar string
144 Specify the TLS protocols to enable.
145 Refer to
146 .Xr tls_config_parse_protocols 3
147 for the valid protocol string values.
148 By default, both TLSv1.3 and TLSv1.2 are enabled.
149 Use
150 .Dq tlsv1.3
151 to enable only TLSv1.3.
152 .It Ic user Ar string
153 Run the daemon as the given user.
154 .El
155 .Ss Servers
156 Every virtual host is defined by a
157 .Ic server
158 block:
159 .Bl -tag -width Ds
160 .It Ic server Ar hostname Brq ...
161 Match the server name using shell globbing rules.
162 It can be an explicit name,
163 .Ar www.example.com ,
164 or a name including a wildcards,
165 .Ar *.example.com .
166 .El
167 .Pp
168 Followed by a block of options that is enclosed in curly brackets:
169 .Bl -tag -width Ds
170 .It Ic alias Ar name
171 Specify an additional alias
172 .Ar name
173 for this server.
174 .It Ic auto Ic index Ar bool
175 If no index file is found, automatically generate a directory listing.
176 Disabled by default.
177 .It Ic block Op Ic return Ar code Op Ar meta
178 Send a reply and close the connection;
179 by default
180 .Ar code
181 is 40
182 and
183 .Ar meta
184 is
185 .Dq temporary failure .
186 If
187 .Ar code
188 is in the 3x range, then
189 .Ar meta
190 is mandatory.
191 Inside
192 .Ar meta ,
193 the following special sequences are supported:
194 .Bl -tag -width Ds -compact
195 .It \&%\&%
196 is replaced with a single
197 .Sq \&% .
198 .It \&%p
199 is replaced with the request path.
200 .It \&%q
201 is replaced with the query string of the request.
202 .It \&%P
203 is replaced with the server port.
204 .It \&%N
205 is replaced with the server name.
206 .El
207 .It Ic cert Ar file
208 Path to the certificate to use for this server.
209 .Ar file
210 should contain a PEM encoded certificate.
211 This option is mandatory.
212 .It Ic default type Ar string
213 Set the default media type that is used if the media type for a
214 specified extension is not found.
215 If not specified, the
216 .Ic default type
217 is set to
218 .Dq application/octet-stream .
219 .It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
220 Enable
221 .Sx FastCGI
222 instead of serving files.
223 The
224 .Ar socket
225 can either be a UNIX-domain socket or a TCP socket.
226 If the FastCGI application is listening on a UNIX domain socket,
227 .Ar socket
228 is a local path name within the
229 .Xr chroot 2
230 root directory of
231 .Nm .
232 Otherwise, the
233 .Ic tcp
234 keyword must be provided and
235 .Ar socket
236 is interpreted as a hostname or an IP address.
237 .Ar port
238 can be either a port number or the name of a service enclosed in
239 double quotes.
240 If not specified defaults to 9000.
241 .It Ic index Ar string
242 Set the directory index file.
243 If not specified, it defaults to
244 .Pa index.gmi .
245 .It Ic key Ar file
246 Specify the private key to use for this server.
247 .Ar file
248 should contain a PEM encoded private key.
249 This option is mandatory.
250 .It Ic lang Ar string
251 Specify the language tag for the text/gemini content served.
252 If not specified, no
253 .Dq lang
254 parameter will be added in the response.
255 .It Ic location Ar path Brq ...
256 Specify server configuration rules for a specific location.
257 .Ar path
258 argument will be matched against the request path with shell globbing
259 rules.
260 In case of multiple location statements in the same context, the first
261 matching location will be put into effect and the later ones ignored.
262 Therefore is advisable to match for more specific paths first and for
263 generic ones later on.
265 .Ic location
266 section may include most of the server configuration rules
267 except
268 .Ic alias , Ic cert , Ic key , Ic location , Ic param No and Ic proxy .
269 .It Ic log Ar bool
270 Enable or disable the logging for the current server or location block.
271 .It Ic param Ar name Cm = Ar value
272 Set the param
273 .Ar name
274 to
275 .Ar value
276 for FastCGI.
277 By default the following parameters are defined:
278 .Bl -tag -width 24m
279 .It Ev GATEWAY_INTERFACE
280 .Dq CGI/1.1
281 .It Ev GEMINI_DOCUMENT_ROOT
282 The root directory of the virtual host.
283 .It Ev GEMINI_SCRIPT_FILENAME
284 Full path to the FastCGI script being executed.
285 .It Ev GEMINI_URL
286 The full IRI of the request.
287 .It Ev GEMINI_URL_PATH
288 The path of the request.
289 .It Ev PATH_INFO
290 The portion of the requested path that is derived from the the IRI
291 path hierarchy following the part that identifies the script itself.
292 Can be unset.
293 .It Ev PATH_TRANSLATED
294 Present if and only if
295 .Ev PATH_INFO
296 is set.
297 It represent the translation of the
298 .Ev PATH_INFO .
299 .Nm gmid
300 builds this by appending the
301 .Ev PATH_INFO
302 to the virtual host directory root.
303 .It Ev QUERY_STRING
304 The decoded query string.
305 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
306 Textual representation of the client IP.
307 .It Ev REQUEST_METHOD
308 This is present only for RFC3875 (CGI) compliance.
309 It's always set to the empty string.
310 .It Ev SCRIPT_NAME
311 The virtual URI path to the script.
312 .It Ev SERVER_NAME
313 The name of the server
314 .It Ev SERVER_PORT
315 The port the server is listening on.
316 .It Ev SERVER_PROTOCOL
317 .Dq GEMINI
318 .It Ev SERVER_SOFTWARE
319 The name and version of the server, i.e.
320 .Dq gmid/1.8.4
321 .It Ev AUTH_TYPE
322 The string "Certificate" if the client used a certificate, otherwise
323 unset.
324 .It Ev REMOTE_USER
325 The subject of the client certificate if provided, otherwise unset.
326 .It Ev TLS_CLIENT_ISSUER
327 The is the issuer of the client certificate if provided, otherwise
328 unset.
329 .It Ev TLS_CLIENT_HASH
330 The hash of the client certificate if provided, otherwise unset.
331 The format is
332 .Dq ALGO:HASH .
333 .It Ev TLS_VERSION
334 The TLS version negotiated with the peer.
335 .It Ev TLS_CIPHER
336 The cipher suite negotiated with the peer.
337 .It Ev TLS_CIPHER_STRENGTH
338 The strength in bits for the symmetric cipher that is being used with
339 the peer.
340 .It Ev TLS_CLIENT_NOT_AFTER
341 The time corresponding to the end of the validity period of the peer
342 certificate in the ISO 8601 format
343 .Pq e.g. Dq 2021-02-07T20:17:41Z .
344 .It Ev TLS_CLIENT_NOT_BEFORE
345 The time corresponding to the start of the validity period of the peer
346 certificate in the ISO 8601 format.
347 .El
348 .It Ic ocsp Ar file
349 Specify an OCSP response to be stapled during TLS handshakes
350 with this server.
351 The
352 .Ar file
353 should contain a DER-format OCSP response retrieved from an
354 OCSP server for the
355 .Ic cert
356 in use.
357 If the OCSP response in
358 .Ar file
359 is empty, OCSP stapling will not be used.
360 The default is to not use OCSP stapling.
361 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host Oo Cm port Ar port Oc Oc Brq ...
362 Set up a reverse proxy.
363 The optional matching rules
364 .Cm proto
365 and
366 .Cm for-host
367 can be used to enable proxying only for protocols matching
368 .Ar name
369 .Po Dq gemini
370 by default
371 .Pc
372 and/or whose request IRI matches
373 .Ar host
374 and
375 .Ar port
376 .Pq 1965 by default .
377 Matching happens using shell globbing rules.
378 .Pp
379 In case of multiple matching proxy blocks in the same context, the
380 first matching proxy will be put into effect and the later ones
381 ignored.
382 .Pp
383 Valid options are:
384 .Bl -tag -width Ds
385 .It Ic cert Ar file
386 Specify the client certificate to use when making requests.
387 .It Ic key Ar file
388 Specify the client certificate key to use when making requests.
389 .It Ic protocols Ar string
390 Specify the TLS protocols allowed when making remote requests.
391 Refer to the
392 .Xr tls_config_parse_protocols 3
393 function for the valid protocol string values.
394 By default, both TLSv1.2 and TLSv1.3 are enabled.
395 .It Ic relay-to Ar host Op Cm port Ar port
396 Relay the request to the given
397 .Ar host
398 at the given
399 .Ar port ,
400 1965 by default.
401 This is the only mandatory option in a
402 .Ic proxy
403 block.
404 .It Ic require Ic client Ic ca Ar file
405 Allow the proxying only from clients that provide a certificate
406 signed by the CA certificate in
407 .Ar file .
408 .It Ic sni Ar hostname
409 Use the given
410 .Ar hostname
411 instead of the one extracted from the
412 .Ic relay-to
413 rule for the TLS handshake with the proxied gemini server.
414 .It Ic use-tls Ar bool
415 Specify whether to use TLS when connecting to the proxied host.
416 Enabled by default.
417 .It Ic verifyname Ar bool
418 Enable or disable the TLS server name verification.
419 Enabled by default.
420 .El
421 .It Ic root Ar directory
422 Specify the root directory for this server
423 .Pq alas the current Dq document root .
424 It's relative to the chroot if enabled.
425 .It Ic require Ic client Ic ca Ar path
426 Allow requests only from clients that provide a certificate signed by
427 the CA certificate in
428 .Ar path .
429 It needs to be a PEM-encoded certificate and it's not relative to the
430 chroot.
431 .It Ic strip Ar number
432 Strip
433 .Ar number
434 components from the beginning of the path before doing a lookup in the
435 root directory.
436 It's also considered for the
437 .Ar meta
438 parameter in the scope of a
439 .Ic block return .
440 .El
441 .Ss Types
442 The
443 .Ic types
444 section must include one or more lines of the following syntax, enclosed
445 in curly brances:
446 .Bl -tag -width Ds
447 .It Ar type/subtype Ar name Op Ar name ...
448 Set the media
449 .Ar type
450 and
451 .Ar subtype
452 to the specified extension
453 .Ar name .
454 One or more names can be specified per line.
455 Earch line may end with an optional semicolon.
456 .It Ic include Ar file
457 Include types definition from an external file, for example
458 .Pa /usr/share/misc/mime.types .
459 .El
460 .Pp
461 By default
462 .Nm gmid
463 uses the following mapping if no
464 .Ic types
465 block is defined:
466 .Bl -tag -offset indent -width 15m -compact
467 .It application/pdf
468 pdf
469 .It image/gif
470 gif
471 .It image/jpeg
472 jpg jpeg
473 .It image/png
474 png
475 .It image/svg+xml
476 svg
477 .It text/gemini
478 gemini gmi
479 .It text/markdown
480 markdown md
481 .It text/x-patch
482 diff patch
483 .It text/xml
484 xml
485 .El
486 .Pp
487 As an exception,
488 .Nm gmid
489 uses the MIME type
490 .Ar text/gemini
491 for file extensions
492 .Ar gemini
493 or
494 .Ar gmi
495 if no mapping was found.
496 .Sh EXAMPLES
497 The following is an example of a possible configuration for a site
498 that enables only TLSv1.3, adds the MIME types mapping from
499 .Pa /usr/share/misc/mime.types
500 and defines two virtual host:
501 .Bd -literal -offset indent
502 ipv6 on # enable ipv6
504 protocols "tlsv1.3"
506 types {
507 include "/usr/share/misc/mime.types"
510 server "example.com" {
511 cert "/etc/ssl/example.com.pem"
512 key "/etc/ssl/private/example.com.key"
513 root "/var/gemini/example.com"
516 server "example.it" {
517 cert "/etc/ssl/example.it.pem"
518 key "/etc/ssl/private/example.it.key"
519 root "/var/gemini/example.it"
521 # set the language for text/gemini files
522 lang "it"
524 .Ed
525 .Pp
526 Yet another example, showing how to enable a
527 .Ic chroot
528 and use
529 .Ic location
530 rule
531 .Bd -literal -offset indent
532 chroot "/var/gemini"
533 user "_gmid"
535 server "example.com" {
536 # absolute paths:
537 cert "/etc/ssl/example.com.pem"
538 key "/etc/ssl/private/example.com.key"
540 # relative to the chroot:
541 root "/example.com"
543 location "/static/*" {
544 # load the following rules only for
545 # requests that matches "/static/*"
547 auto index on
548 index "index.gemini"
551 .Ed
552 .Sh SEE ALSO
553 .Xr gmid 8 ,
554 .Xr slowcgi 8
555 .Sh AUTHORS
556 .An -nosplit
557 The
558 .Nm gmid
559 program was written by
560 .An Omar Polo Aq Mt op@omarpolo.com .