Blob


1 .\" Copyright (c) 2022, 2023, 2024 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 June 28, 2024
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 the following sections:
27 .Bl -tag -width Ds
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 .Xr gmid 8 .
34 .It Sy Types
35 Media types and extensions.
36 .It Sy Servers
37 Virtual hosts definition.
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 ext_ip = "10.0.0.1"
103 dir = "/var/gemini"
104 certdir = "/etc/keys"
105 common = "lang it; auto index on"
107 server "foo" {
108 listen on $ext_ip
109 root $dir "/foo" # "/var/gemini/foo"
110 cert $certdir "/foo.pem" # "/etc/keys/foo.pem"
111 key $certdir "/foo.key" # "/etc/keys/foo.key"
112 @common
114 .Ed
115 .Ss Global Options
116 .Bl -tag -width 12m
117 .It Ic chroot Ar path
118 .Xr chroot 2
119 the process to the given
120 .Ar path .
121 The daemon has to be run with root privileges and thus the option
122 .Ic user
123 needs to be provided too, so privileges can be dropped afterwards.
124 All the paths in the configuration file are relative to the chroot
125 directory, except for the
126 .Ic cert ,
127 .Ic key
128 and
129 .Ic ocsp
130 paths.
131 Defaults to the
132 .Ic user
133 home directory, if provided.
134 .It Ic log Ar options
135 Specify logging options.
136 Multiple options may be provided within curly braces.
137 The available options are as follows:
138 .Bl -tag -width Ds
139 .It Ic access Ar file
140 Log the requests to
141 .Ar file .
142 The path is relative to the
143 .Ic chroot .
144 .It Ic style Ar style
145 Set the logging style, defaults to
146 .Ic legacy .
147 The
148 .Ar style
149 can be one of:
150 .Bl -tag -width Ds
151 .It Ic common
152 Attempt to be compatible with the default Apache httpd log format.
153 Each line is formatted as follows: the matching host name,
154 the remote IP address, one dash
155 .Sq - ,
156 Common Name of the client certificate
157 .Pq if provided, '-' otherwise ,
158 the timestamp of the request, the request URI wrapped in double quotes,
159 the response code and the size of the response.
160 .It Ic combined
161 Attempt to be compatible with the default nginx log format.
162 Each line is formatted as follows: the remote IP address, one dash
163 .Sq - ,
164 Common Name of the client certificate
165 .Pq if provided, '-' otherwise ,
166 the timestamp wrapped in square brackets, the request URI wrapped in
167 double quotes, the response code, the size of the response, a dash
168 wrapped in double quotes and "".
169 The strangness of these two last fields is because Gemini doesn't have
170 the notion of the
171 .Dq Referer
172 header nor the
173 .Dq User-agent .
174 .\" .It Ic condensed
175 .\" The native
176 .\" .Xr gmid 8
177 .\" format since 2.0.
178 .\" Each line is formatted as follows: RFC 3339 date time,
179 .\" remote IP address, Common Name of the client certificate
180 .\" .Pq if provided, '-' otherwise ,
181 .\" the matching host name, the request URI, the size of the request,
182 .\" the size of the response, the response code and meta.
183 .It Ic legacy
184 Each line is formatted as follows: the remote IP address and port, the
185 .Sq GET
186 keyword, the request URI, the response code and meta.
187 .El
188 .It Ic syslog Op Ic off
189 Log to syslog.
190 It is enabled by default, use the
191 .Ic off
192 argument to disable.
193 .It Ic syslog facility Ar facility
194 Log to
195 .Xr syslog 3
196 using specified
197 .Ar facility .
198 Available facilities are as follows: daemon, ftp, local0 through local7 and
199 user.
200 These are case insensitive and can be prefixed with
201 .Sq LOG_ .
202 Not all level may be available on all operating systems.
203 The default facility is
204 .Ev LOG_DAEMON .
205 .El
206 .It Ic prefork Ar number
207 Run the specified number of server processes.
208 This increases the performance and prevents delays when connecting to
209 a server.
210 .Xr gmid 8
211 runs 3 server processes by default.
212 The maximum number allowed is 16.
213 .It Ic protocols Ar string
214 Specify the TLS protocols to enable.
215 Refer to
216 .Xr tls_config_parse_protocols 3
217 for the valid protocol string values.
218 By default, both TLSv1.3 and TLSv1.2 are enabled.
219 Use
220 .Dq tlsv1.3
221 to enable only TLSv1.3.
222 .It Ic user Ar string
223 Run the daemon as the given user.
224 Mandatory if the
225 .Ic chroot
226 option is used.
227 .El
228 .Ss Servers
229 Every virtual host is defined by a
230 .Ic server
231 block:
232 .Bl -tag -width Ds
233 .It Ic server Ar hostname Brq ...
234 Match the server name using shell globbing rules.
235 It can be an explicit name,
236 .Ar www.example.com ,
237 or a name including wildcards,
238 .Ar *.example.com .
239 .El
240 .Pp
241 Followed by a block of options that is enclosed in curly brackets:
242 .Bl -tag -width Ds
243 .It Ic alias Ar name
244 Specify an additional alias
245 .Ar name
246 for this server.
247 .It Ic auto Ic index Ar bool
248 If no index file is found, automatically generate a directory listing.
249 Disabled by default.
250 .It Ic block Op Ic return Ar code Op Ar meta
251 Send a reply and close the connection;
252 by default
253 .Ar code
254 is 40
255 and
256 .Ar meta
257 is
258 .Dq temporary failure .
259 If
260 .Ar code
261 is in the 3x range, then
262 .Ar meta
263 is mandatory.
264 Inside
265 .Ar meta ,
266 the following special sequences are supported:
267 .Bl -tag -width Ds -compact
268 .It \&%\&%
269 is replaced with a single
270 .Sq \&% .
271 .It \&%p
272 is replaced with the request path.
273 .It \&%q
274 is replaced with the query string of the request.
275 .It \&%P
276 is replaced with the server port.
277 .It \&%N
278 is replaced with the server name.
279 .El
280 .It Ic cert Ar file
281 Path to the certificate to use for this server.
282 .Ar file
283 should contain a PEM encoded certificate.
284 This option is mandatory.
285 .It Ic default type Ar string
286 Set the default media type that is used if the media type for a
287 specified extension is not found.
288 If not specified, the
289 .Ic default type
290 is set to
291 .Dq application/octet-stream .
292 .It Ic fastcgi Ar option
293 Enable FastCGI instead of serving files.
294 Multiple options may be specified within curly braces.
295 Valid options are:
296 .Bl -tag -width Ds
297 .It Ic param Ar name Cm = Ar value
298 Set the param
299 .Ar name
300 to
301 .Ar value .
302 .It Ic socket Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
303 The
304 .Ar socket
305 can either be a UNIX-domain socket or a TCP socket.
306 If the FastCGI application is listening on a UNIX domain socket,
307 .Ar socket
308 is a local path name within the
309 .Xr chroot 2
310 root directory of
311 .Xr gmid 8 .
312 Otherwise, the
313 .Ic tcp
314 keyword must be provided and
315 .Ar socket
316 is interpreted as a hostname or an IP address.
317 .Ar port
318 can be either a port number or the name of a service enclosed in
319 double quotes.
320 If not specified defaults to 9000.
321 .It Ic strip Ar number
322 Strip
323 .Ar number
324 leading path components from the request URL before splitting it in
325 .Ev SCRIPT_NAME
326 and
327 .Ev PATH_INFO .
328 .El
329 .Pp
330 The FastCGI handler will be given the following variables by default:
331 .Bl -tag -width 24m
332 .\" .It Ev GEMINI_DOCUMENT_ROOT
333 .\" The root directory of the virtual host.
334 .It Ev GEMINI_URL_PATH
335 Full path of the request.
336 .It Ev GEMINI_SEARCH_STRING
337 The decoded
338 .Ev QUERY_STRING
339 if defined in the request and if it doesn't contain any unencoded
340 .Sq =
341 characters, otherwise unset.
342 .It Ev GATEWAY_INTERFACE
343 .Dq CGI/1.1
344 .It Ev AUTH_TYPE
345 The string "Certificate" if the client used a certificate, otherwise
346 unset.
347 .It Ev PATH_INFO
348 The portion of the requested path that is derived from the the IRI
349 path hierarchy following
350 .Ev SCRIPT_NAME .
351 Can be unset.
352 .It Ev PATH_TRANSLATED
353 Present if and only if
354 .Ev PATH_INFO
355 is set.
356 It represent the translation of the
357 .Ev PATH_INFO .
358 .Nm gmid
359 builds this by appending the
360 .Ev PATH_INFO
361 to the virtual host directory root.
362 .It Ev QUERY_STRING
363 The URL-encoded search or parameter string.
364 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
365 Textual representation of the client IP.
366 .It Ev REQUEST_METHOD
367 This is present only for RFC3875 (CGI) compliance.
368 It's always set to
369 .Dq GET .
370 .It Ev SCRIPT_NAME
371 The virtual URI path to the script.
372 Since it's impossible to determine in all cases the correct
373 .Ev SCRIPT_NAME
374 programmatically
375 .Nm gmid
376 assumes it's the empty string.
377 It is recommended to manually specify this parameter when serving a
378 sub-tree of a virtual host via FastCGI.
379 .It Ev SERVER_NAME
380 The name of the server
381 .It Ev SERVER_PORT
382 The port the server is listening on.
383 .It Ev SERVER_PROTOCOL
384 .Dq GEMINI
385 .It Ev SERVER_SOFTWARE
386 The name and version of the server, i.e.
387 .Dq gmid/2.0.5
388 .It Ev REMOTE_USER
389 The subject of the client certificate if provided, otherwise unset.
390 .It Ev TLS_CLIENT_ISSUER
391 The is the issuer of the client certificate if provided, otherwise
392 unset.
393 .It Ev TLS_CLIENT_HASH
394 The hash of the client certificate if provided, otherwise unset.
395 The format is
396 .Dq ALGO:HASH .
397 .It Ev TLS_VERSION
398 The TLS version negotiated with the peer.
399 .It Ev TLS_CIPHER
400 The cipher suite negotiated with the peer.
401 .It Ev TLS_CIPHER_STRENGTH
402 The strength in bits for the symmetric cipher that is being used with
403 the peer.
404 .It Ev TLS_CLIENT_NOT_AFTER
405 The time corresponding to the end of the validity period of the peer
406 certificate in the ISO 8601 format
407 .Pq e.g. Dq 2021-02-07T20:17:41Z .
408 .It Ev TLS_CLIENT_NOT_BEFORE
409 The time corresponding to the start of the validity period of the peer
410 certificate in the ISO 8601 format.
411 .El
412 .It Ic fastcgi off
413 Disable FastCGI handling in the current location.
414 .It Ic index Ar string
415 Set the directory index file.
416 If not specified, it defaults to
417 .Pa index.gmi .
418 .It Ic key Ar file
419 Specify the private key to use for this server.
420 .Ar file
421 should contain a PEM encoded private key.
422 This option is mandatory.
423 .It Ic lang Ar string
424 Specify the language tag for the text/gemini content served.
425 If not specified, no
426 .Dq lang
427 parameter will be added in the response.
428 .It Ic listen on Ar address Oo Ic port Ar number Oc Op Ic proxy-v1
429 Set the listen
430 .Ar address
431 and
432 .Ar port
433 which defaults to
434 .Sq 1965 .
435 This statement can be specified multiple times.
436 If
437 .Ar address
438 is
439 .Sq *
440 then
441 .Xr gmid 8
442 will listen on all IPv4 and IPv6 addresses.
443 .Ar 0.0.0.0
444 can be used to listen on all IPv4 addresses and
445 .Ar ::
446 on all IPv6 addresses.
447 If
448 .Ic proxy-v1
449 is specified, then connections speaking the proxy protocol v1 are
450 expected on this listener.
451 If multiple
452 .Ic listen
453 directive share the same
454 .Ar address
455 and
456 .Ar port ,
457 then all of them must have or lack
458 .Ic proxy-v1 .
459 .It Ic location Ar path Brq ...
460 Specify server configuration rules for a specific location.
461 .Ar path
462 argument will be matched against the request path with shell globbing
463 rules.
464 In case of multiple location statements in the same context, the first
465 matching location will be put into effect and the later ones ignored.
466 Therefore is advisable to match for more specific paths first and for
467 generic ones later on.
469 .Ic location
470 section may include most of the server configuration rules
471 except
472 .Ic alias , Ic cert , Ic key , Ic listen , Ic location
473 and
474 .Ic proxy .
475 .It Ic log Ar bool
476 Enable or disable the logging for the current server or location block.
477 .It Ic ocsp Ar file
478 Specify an OCSP response to be stapled during TLS handshakes
479 with this server.
480 The
481 .Ar file
482 should contain a DER-format OCSP response retrieved from an
483 OCSP server for the
484 .Ic cert
485 in use.
486 If the OCSP response in
487 .Ar file
488 is empty, OCSP stapling will not be used.
489 The default is to not use OCSP stapling.
490 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host Oo Cm port Ar port Oc Oc Brq ...
491 Set up a reverse proxy.
492 The optional matching rules
493 .Cm proto
494 and
495 .Cm for-host
496 can be used to enable proxying only for protocols matching
497 .Ar name
498 .Po Dq gemini
499 by default
500 .Pc
501 and/or whose request IRI matches
502 .Ar host
503 and
504 .Ar port
505 .Pq 1965 by default .
506 Matching happens using shell globbing rules.
507 .Pp
508 In case of multiple matching proxy blocks in the same context, the
509 first matching proxy will be put into effect and the later ones
510 ignored.
511 .Pp
512 Valid options are:
513 .Bl -tag -width Ds
514 .It Ic cert Ar file
515 Specify the client certificate to use when making requests.
516 .It Ic key Ar file
517 Specify the client certificate key to use when making requests.
518 .It Ic protocols Ar string
519 Specify the TLS protocols allowed when making remote requests.
520 Refer to the
521 .Xr tls_config_parse_protocols 3
522 function for the valid protocol string values.
523 By default, both TLSv1.2 and TLSv1.3 are enabled.
524 .It Ic relay-to Ar host Op Cm port Ar port
525 Relay the request to the given
526 .Ar host
527 at the given
528 .Ar port ,
529 1965 by default.
530 This is the only mandatory option in a
531 .Ic proxy
532 block.
533 .It Ic require Ic client Ic ca Ar file
534 Allow the proxying only from clients that provide a certificate
535 signed by the CA certificate in
536 .Ar file .
537 .It Ic sni Ar hostname
538 Use the given
539 .Ar hostname
540 instead of the one extracted from the
541 .Ic relay-to
542 rule for the TLS handshake with the proxied gemini server.
543 .It Ic use-tls Ar bool
544 Specify whether to use TLS when connecting to the proxied host.
545 Enabled by default.
546 .It Ic verifyname Ar bool
547 Enable or disable the TLS server name verification.
548 Enabled by default.
549 .El
550 .It Ic root Ar directory
551 Specify the root directory for this server
552 .Pq alas the current Dq document root .
553 It's relative to the chroot if enabled.
554 .It Ic require Ic client Ic ca Ar path
555 Allow requests only from clients that provide a certificate signed by
556 the CA certificate in
557 .Ar path .
558 It needs to be a PEM-encoded certificate and it's not relative to the
559 chroot.
560 .It Ic strip Ar number
561 Strip
562 .Ar number
563 components from the beginning of the path before doing a lookup in the
564 root directory.
565 It's also considered for the
566 .Ar meta
567 parameter in the scope of a
568 .Ic block return .
569 .El
570 .Ss Types
571 The
572 .Ic types
573 section must include one or more lines of the following syntax, enclosed
574 in curly brances:
575 .Bl -tag -width Ds
576 .It Ar type Ns / Ns Ar subtype Ar name Op Ar name ...
577 Set the media
578 .Ar type
579 and
580 .Ar subtype
581 to the specified extension
582 .Ar name .
583 One or more names can be specified per line.
584 Earch line may end with an optional semicolon.
585 .It Ic include Ar file
586 Include types definition from an external file, for example
587 .Pa /usr/share/misc/mime.types .
588 .El
589 .Pp
590 By default
591 .Nm gmid
592 uses the following mapping if no
593 .Ic types
594 block is defined:
595 .Pp
596 .Bl -tag -offset indent -width 15m -compact
597 .It application/pdf
598 pdf
599 .It image/gif
600 gif
601 .It image/jpeg
602 jpg jpeg
603 .It image/png
604 png
605 .It image/svg+xml
606 svg
607 .It text/gemini
608 gemini gmi
609 .It text/markdown
610 markdown md
611 .It text/x-patch
612 diff patch
613 .It text/xml
614 xml
615 .El
616 .Pp
617 As an exception,
618 .Nm gmid
619 uses the MIME type
620 .Ar text/gemini
621 for file extensions
622 .Ar gemini
623 or
624 .Ar gmi
625 if no mapping was found.
626 .Sh EXAMPLES
627 The following is an example of a possible configuration for a site
628 that enables only TLSv1.3, adds the MIME types mapping from
629 .Pa /usr/share/misc/mime.types
630 and defines two virtual host:
631 .Bd -literal -offset indent
632 protocols "tlsv1.3"
634 types {
635 include "/usr/share/misc/mime.types"
638 server "example.com" {
639 listen on * port 1965
640 cert "/etc/ssl/example.com.pem"
641 key "/etc/ssl/private/example.com.key"
642 root "/var/gemini/example.com"
645 server "example.it" {
646 listen on * port 1965
647 cert "/etc/ssl/example.it.pem"
648 key "/etc/ssl/private/example.it.key"
649 root "/var/gemini/example.it"
651 # set the language for text/gemini files
652 lang "it"
654 .Ed
655 .Pp
656 Yet another example, showing how to enable a
657 .Ic chroot
658 and use
659 .Ic location
660 rule
661 .Bd -literal -offset indent
662 chroot "/var/gemini"
663 user "_gmid"
665 server "example.com" {
666 listen on * port 1965
668 # absolute paths:
669 cert "/etc/ssl/example.com.pem"
670 key "/etc/ssl/private/example.com.key"
672 # relative to the chroot:
673 root "/example.com"
675 location "/static/*" {
676 # load the following rules only for
677 # requests that matches "/static/*"
679 auto index on
680 index "index.gemini"
683 .Ed
684 .Pp
685 This shows how to set up a reverse proxy: all request for
686 .Sq example.com
687 will be forwarded to 10.0.0.6 transparently.
688 Proxying establish a new TLS connection, so any client-certificates used
689 to connect to
690 .Xr gmid 8
691 cannot be provided to the proxied server as well.
692 .Bd -literal -offset indent
693 server "example.com" {
694 listen on * port 1965
695 cert "/etc/ssl/example.com.pem"
696 key "/etc/ssl/private/example.com.key"
697 proxy {
698 relay-to 10.0.0.6 port 1965
701 .Ed
702 .Sh SEE ALSO
703 .Xr gmid 8 ,
704 .Xr slowcgi 8
705 .Sh AUTHORS
706 .An -nosplit
707 The
708 .Nm gmid
709 program was written by
710 .An Omar Polo Aq Mt op@omarpolo.com .