1 .\" Copyright (c) 2022, 2023 Omar Polo <op@omarpolo.com>
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.
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.
19 .Nd gmid Gemini server configuration file
22 is the configuration file format for the
26 The configuration file is divided into the following sections:
29 User-defined variables may be defined and used later, simplifying the
35 Virtual hosts definition.
37 Media types and extensions.
40 Within the sections, empty lines are ignored and comments can be put
41 anywhere in the file using a hash mark
43 and extend to the end of the current line.
44 A boolean is either the symbol
48 A string is a sequence of characters wrapped in double quotes,
50 Multiple strings one next to the other are joined into a single
52 .Bd -literal -offset indent
53 # equivalent to "temporary-failure"
54 block return 40 "temporary" "-" "failure"
57 Furthermore, quoting is necessary only when a string needs to contain
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
66 Strict ordering of the sections is not enforced, so that is possible
67 to mix macros, options and
70 However, defining all the
72 blocks after the macros and the global options is recommended.
74 Newlines are often optional, except around top-level instructions, and
77 can also be optionally used to separate options.
79 Additional configuration files can be included with the
82 .Bd -literal -offset indent
83 include "/etc/gmid.conf.local"
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.
92 Two kinds of macros are supported: variable-like and proper macros.
93 When a macro is invoked with a
95 before its name its expanded as a string, whereas when it's invoked
98 its expanded in-place.
101 .Bd -literal -offset indent
103 certdir = "/etc/keys"
104 common = "lang it; auto index on"
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"
115 .It Ic chroot Ar path
117 the process to the given
119 The daemon has to be run with root privileges and thus the option
121 needs to be provided too, so privileges can be dropped afterwards.
122 All the paths in the configuration file are relative to the chroot
123 directory, except for the
131 home directory, if provided.
132 .It Ic prefork Ar number
133 Run the specified number of server processes.
134 This increases the performance and prevents delays when connecting to
137 runs 3 server processes by default.
138 The maximum number allowed is 16.
139 .It Ic protocols Ar string
140 Specify the TLS protocols to enable.
142 .Xr tls_config_parse_protocols 3
143 for the valid protocol string values.
144 By default, both TLSv1.3 and TLSv1.2 are enabled.
147 to enable only TLSv1.3.
148 .It Ic user Ar string
149 Run the daemon as the given user.
152 Every virtual host is defined by a
156 .It Ic server Ar hostname Brq ...
157 Match the server name using shell globbing rules.
158 It can be an explicit name,
159 .Ar www.example.com ,
160 or a name including a wildcards,
164 Followed by a block of options that is enclosed in curly brackets:
167 Specify an additional alias
170 .It Ic auto Ic index Ar bool
171 If no index file is found, automatically generate a directory listing.
173 .It Ic block Op Ic return Ar code Op Ar meta
174 Send a reply and close the connection;
181 .Dq temporary failure .
184 is in the 3x range, then
189 the following special sequences are supported:
190 .Bl -tag -width Ds -compact
192 is replaced with a single
195 is replaced with the request path.
197 is replaced with the query string of the request.
199 is replaced with the server port.
201 is replaced with the server name.
204 Path to the certificate to use for this server.
206 should contain a PEM encoded certificate.
207 This option is mandatory.
208 .It Ic default type Ar string
209 Set the default media type that is used if the media type for a
210 specified extension is not found.
211 If not specified, the
214 .Dq application/octet-stream .
215 .It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
218 instead of serving files.
221 can either be a UNIX-domain socket or a TCP socket.
222 If the FastCGI application is listening on a UNIX domain socket,
224 is a local path name within the
230 keyword must be provided and
232 is interpreted as a hostname or an IP address.
234 can be either a port number or the name of a service enclosed in
236 If not specified defaults to 9000.
237 .It Ic index Ar string
238 Set the directory index file.
239 If not specified, it defaults to
242 Specify the private key to use for this server.
244 should contain a PEM encoded private key.
245 This option is mandatory.
246 .It Ic lang Ar string
247 Specify the language tag for the text/gemini content served.
250 parameter will be added in the response.
251 .It Ic listen on Ar address Op Ic port Ar number
258 This statement can be specified multiple times.
265 will listen on all IPv4 and IPv6 addresses.
267 can be used to listen on all IPv4 addresses and
269 on all IPv6 addresses.
270 .It Ic location Ar path Brq ...
271 Specify server configuration rules for a specific location.
273 argument will be matched against the request path with shell globbing
275 In case of multiple location statements in the same context, the first
276 matching location will be put into effect and the later ones ignored.
277 Therefore is advisable to match for more specific paths first and for
278 generic ones later on.
281 section may include most of the server configuration rules
283 .Ic alias , Ic cert , Ic key , Ic listen , Ic location , Ic param
287 Enable or disable the logging for the current server or location block.
288 .It Ic param Ar name Cm = Ar value
294 By default the following parameters are defined:
296 .It Ev GATEWAY_INTERFACE
298 .It Ev GEMINI_DOCUMENT_ROOT
299 The root directory of the virtual host.
300 .It Ev GEMINI_SCRIPT_FILENAME
301 Full path to the FastCGI script being executed.
303 The full IRI of the request.
304 .It Ev GEMINI_URL_PATH
305 The path of the request.
306 .It Ev GEMINI_SEARCH_STRING
309 if defined in the request and if it doesn't contain any unencoded
311 characters, otherwise unset.
313 The portion of the requested path that is derived from the the IRI
314 path hierarchy following the part that identifies the script itself.
316 .It Ev PATH_TRANSLATED
317 Present if and only if
320 It represent the translation of the
323 builds this by appending the
325 to the virtual host directory root.
327 The URL-encoded search or parameter string.
328 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
329 Textual representation of the client IP.
330 .It Ev REQUEST_METHOD
331 This is present only for RFC3875 (CGI) compliance.
332 It's always set to the empty string.
334 The virtual URI path to the script.
336 The name of the server
338 The port the server is listening on.
339 .It Ev SERVER_PROTOCOL
341 .It Ev SERVER_SOFTWARE
342 The name and version of the server, i.e.
345 The string "Certificate" if the client used a certificate, otherwise
348 The subject of the client certificate if provided, otherwise unset.
349 .It Ev TLS_CLIENT_ISSUER
350 The is the issuer of the client certificate if provided, otherwise
352 .It Ev TLS_CLIENT_HASH
353 The hash of the client certificate if provided, otherwise unset.
357 The TLS version negotiated with the peer.
359 The cipher suite negotiated with the peer.
360 .It Ev TLS_CIPHER_STRENGTH
361 The strength in bits for the symmetric cipher that is being used with
363 .It Ev TLS_CLIENT_NOT_AFTER
364 The time corresponding to the end of the validity period of the peer
365 certificate in the ISO 8601 format
366 .Pq e.g. Dq 2021-02-07T20:17:41Z .
367 .It Ev TLS_CLIENT_NOT_BEFORE
368 The time corresponding to the start of the validity period of the peer
369 certificate in the ISO 8601 format.
372 Specify an OCSP response to be stapled during TLS handshakes
376 should contain a DER-format OCSP response retrieved from an
380 If the OCSP response in
382 is empty, OCSP stapling will not be used.
383 The default is to not use OCSP stapling.
384 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host Oo Cm port Ar port Oc Oc Brq ...
385 Set up a reverse proxy.
386 The optional matching rules
390 can be used to enable proxying only for protocols matching
395 and/or whose request IRI matches
399 .Pq 1965 by default .
400 Matching happens using shell globbing rules.
402 In case of multiple matching proxy blocks in the same context, the
403 first matching proxy will be put into effect and the later ones
409 Specify the client certificate to use when making requests.
411 Specify the client certificate key to use when making requests.
412 .It Ic protocols Ar string
413 Specify the TLS protocols allowed when making remote requests.
415 .Xr tls_config_parse_protocols 3
416 function for the valid protocol string values.
417 By default, both TLSv1.2 and TLSv1.3 are enabled.
418 .It Ic relay-to Ar host Op Cm port Ar port
419 Relay the request to the given
424 This is the only mandatory option in a
427 .It Ic require Ic client Ic ca Ar file
428 Allow the proxying only from clients that provide a certificate
429 signed by the CA certificate in
431 .It Ic sni Ar hostname
434 instead of the one extracted from the
436 rule for the TLS handshake with the proxied gemini server.
437 .It Ic use-tls Ar bool
438 Specify whether to use TLS when connecting to the proxied host.
440 .It Ic verifyname Ar bool
441 Enable or disable the TLS server name verification.
444 .It Ic root Ar directory
445 Specify the root directory for this server
446 .Pq alas the current Dq document root .
447 It's relative to the chroot if enabled.
448 .It Ic require Ic client Ic ca Ar path
449 Allow requests only from clients that provide a certificate signed by
450 the CA certificate in
452 It needs to be a PEM-encoded certificate and it's not relative to the
454 .It Ic strip Ar number
457 components from the beginning of the path before doing a lookup in the
459 It's also considered for the
461 parameter in the scope of a
467 section must include one or more lines of the following syntax, enclosed
470 .It Ar type Ns / Ns Ar subtype Ar name Op Ar name ...
475 to the specified extension
477 One or more names can be specified per line.
478 Earch line may end with an optional semicolon.
479 .It Ic include Ar file
480 Include types definition from an external file, for example
481 .Pa /usr/share/misc/mime.types .
486 uses the following mapping if no
490 .Bl -tag -offset indent -width 15m -compact
519 if no mapping was found.
521 The following is an example of a possible configuration for a site
522 that enables only TLSv1.3, adds the MIME types mapping from
523 .Pa /usr/share/misc/mime.types
524 and defines two virtual host:
525 .Bd -literal -offset indent
529 include "/usr/share/misc/mime.types"
532 server "example.com" {
533 listen on * port 1965
534 cert "/etc/ssl/example.com.pem"
535 key "/etc/ssl/private/example.com.key"
536 root "/var/gemini/example.com"
539 server "example.it" {
540 listen on * port 1965
541 cert "/etc/ssl/example.it.pem"
542 key "/etc/ssl/private/example.it.key"
543 root "/var/gemini/example.it"
545 # set the language for text/gemini files
550 Yet another example, showing how to enable a
555 .Bd -literal -offset indent
559 server "example.com" {
560 listen on * port 1965
563 cert "/etc/ssl/example.com.pem"
564 key "/etc/ssl/private/example.com.key"
566 # relative to the chroot:
569 location "/static/*" {
570 # load the following rules only for
571 # requests that matches "/static/*"
585 program was written by
586 .An Omar Polo Aq Mt op@omarpolo.com .
