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 log Ar options
133 Specify logging options.
134 Multiple options may be provided within curly braces.
135 The available options are as follows:
137 .It Ic syslog Op Ic off
139 It is enabled by default, use the
142 .It Ic access Ar file
145 The path is relative to the
147 .It Ic style Ar style
148 Set the logging style, defaults to
155 Attempt to be compatible with the default Apache httpd log format.
156 Each line is formatted as follows: the matching host name,
157 the remote IP address, one dash
159 Common Name of the client certificate
160 .Pq if provided, '-' otherwise ,
161 the timestamp of the request, the request URI wrapped in double quotes,
162 the response code and the size of the response.
164 Attempt to be compatible with the default nginx log format.
165 Each line is formatted as follows: the remote IP address, one dash
167 Common Name of the client certificate
168 .Pq if provided, '-' otherwise ,
169 the timestamp wrapped in square brackets, the request URI wrapped in
170 double quotes, the response code, the size of the response, a dash
171 wrapped in double quotes and "".
172 The strangness of these two last fields is because Gemini doesn't have
181 Each line is formatted as follows: RFC 3339 date time,
182 remote IP address, Common Name of the client certificate
183 .Pq if provided, '-' otherwise ,
184 the matching host name, the request URI, the size of the response,
185 the response code and meta.
187 The pre-2.0 gmid native format.
188 Each line is formatted as follows: the remote IP address and port, the
190 keyword, the request URI, the response code and meta.
193 .It Ic prefork Ar number
194 Run the specified number of server processes.
195 This increases the performance and prevents delays when connecting to
198 runs 3 server processes by default.
199 The maximum number allowed is 16.
200 .It Ic protocols Ar string
201 Specify the TLS protocols to enable.
203 .Xr tls_config_parse_protocols 3
204 for the valid protocol string values.
205 By default, both TLSv1.3 and TLSv1.2 are enabled.
208 to enable only TLSv1.3.
209 .It Ic user Ar string
210 Run the daemon as the given user.
213 Every virtual host is defined by a
217 .It Ic server Ar hostname Brq ...
218 Match the server name using shell globbing rules.
219 It can be an explicit name,
220 .Ar www.example.com ,
221 or a name including a wildcards,
225 Followed by a block of options that is enclosed in curly brackets:
228 Specify an additional alias
231 .It Ic auto Ic index Ar bool
232 If no index file is found, automatically generate a directory listing.
234 .It Ic block Op Ic return Ar code Op Ar meta
235 Send a reply and close the connection;
242 .Dq temporary failure .
245 is in the 3x range, then
250 the following special sequences are supported:
251 .Bl -tag -width Ds -compact
253 is replaced with a single
256 is replaced with the request path.
258 is replaced with the query string of the request.
260 is replaced with the server port.
262 is replaced with the server name.
265 Path to the certificate to use for this server.
267 should contain a PEM encoded certificate.
268 This option is mandatory.
269 .It Ic default type Ar string
270 Set the default media type that is used if the media type for a
271 specified extension is not found.
272 If not specified, the
275 .Dq application/octet-stream .
276 .It Ic fastcgi Ar option
277 Enable FastCGI instead of serving files.
278 Multiple options may be specified within curly braces.
281 .It Ic param Ar name Cm = Ar value
286 .It Ic socket Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
289 can either be a UNIX-domain socket or a TCP socket.
290 If the FastCGI application is listening on a UNIX domain socket,
292 is a local path name within the
298 keyword must be provided and
300 is interpreted as a hostname or an IP address.
302 can be either a port number or the name of a service enclosed in
304 If not specified defaults to 9000.
307 The FastCGI handler will be given the following variables by default:
309 .It Ev GATEWAY_INTERFACE
311 .It Ev GEMINI_DOCUMENT_ROOT
312 The root directory of the virtual host.
313 .It Ev GEMINI_SCRIPT_FILENAME
314 Full path to the FastCGI script being executed.
316 The full IRI of the request.
317 .It Ev GEMINI_URL_PATH
318 The path of the request.
319 .It Ev GEMINI_SEARCH_STRING
322 if defined in the request and if it doesn't contain any unencoded
324 characters, otherwise unset.
326 The portion of the requested path that is derived from the the IRI
327 path hierarchy following the part that identifies the script itself.
329 .It Ev PATH_TRANSLATED
330 Present if and only if
333 It represent the translation of the
336 builds this by appending the
338 to the virtual host directory root.
340 The URL-encoded search or parameter string.
341 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
342 Textual representation of the client IP.
343 .It Ev REQUEST_METHOD
344 This is present only for RFC3875 (CGI) compliance.
345 It's always set to the empty string.
347 The virtual URI path to the script.
349 The name of the server
351 The port the server is listening on.
352 .It Ev SERVER_PROTOCOL
354 .It Ev SERVER_SOFTWARE
355 The name and version of the server, i.e.
358 The string "Certificate" if the client used a certificate, otherwise
361 The subject of the client certificate if provided, otherwise unset.
362 .It Ev TLS_CLIENT_ISSUER
363 The is the issuer of the client certificate if provided, otherwise
365 .It Ev TLS_CLIENT_HASH
366 The hash of the client certificate if provided, otherwise unset.
370 The TLS version negotiated with the peer.
372 The cipher suite negotiated with the peer.
373 .It Ev TLS_CIPHER_STRENGTH
374 The strength in bits for the symmetric cipher that is being used with
376 .It Ev TLS_CLIENT_NOT_AFTER
377 The time corresponding to the end of the validity period of the peer
378 certificate in the ISO 8601 format
379 .Pq e.g. Dq 2021-02-07T20:17:41Z .
380 .It Ev TLS_CLIENT_NOT_BEFORE
381 The time corresponding to the start of the validity period of the peer
382 certificate in the ISO 8601 format.
385 Disable FastCGI handling in the current location.
386 .It Ic index Ar string
387 Set the directory index file.
388 If not specified, it defaults to
391 Specify the private key to use for this server.
393 should contain a PEM encoded private key.
394 This option is mandatory.
395 .It Ic lang Ar string
396 Specify the language tag for the text/gemini content served.
399 parameter will be added in the response.
400 .It Ic listen on Ar address Op Ic port Ar number
407 This statement can be specified multiple times.
414 will listen on all IPv4 and IPv6 addresses.
416 can be used to listen on all IPv4 addresses and
418 on all IPv6 addresses.
419 .It Ic location Ar path Brq ...
420 Specify server configuration rules for a specific location.
422 argument will be matched against the request path with shell globbing
424 In case of multiple location statements in the same context, the first
425 matching location will be put into effect and the later ones ignored.
426 Therefore is advisable to match for more specific paths first and for
427 generic ones later on.
430 section may include most of the server configuration rules
432 .Ic alias , Ic cert , Ic key , Ic listen , Ic location
436 Enable or disable the logging for the current server or location block.
438 Specify an OCSP response to be stapled during TLS handshakes
442 should contain a DER-format OCSP response retrieved from an
446 If the OCSP response in
448 is empty, OCSP stapling will not be used.
449 The default is to not use OCSP stapling.
450 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host Oo Cm port Ar port Oc Oc Brq ...
451 Set up a reverse proxy.
452 The optional matching rules
456 can be used to enable proxying only for protocols matching
461 and/or whose request IRI matches
465 .Pq 1965 by default .
466 Matching happens using shell globbing rules.
468 In case of multiple matching proxy blocks in the same context, the
469 first matching proxy will be put into effect and the later ones
475 Specify the client certificate to use when making requests.
477 Specify the client certificate key to use when making requests.
478 .It Ic protocols Ar string
479 Specify the TLS protocols allowed when making remote requests.
481 .Xr tls_config_parse_protocols 3
482 function for the valid protocol string values.
483 By default, both TLSv1.2 and TLSv1.3 are enabled.
484 .It Ic relay-to Ar host Op Cm port Ar port
485 Relay the request to the given
490 This is the only mandatory option in a
493 .It Ic require Ic client Ic ca Ar file
494 Allow the proxying only from clients that provide a certificate
495 signed by the CA certificate in
497 .It Ic sni Ar hostname
500 instead of the one extracted from the
502 rule for the TLS handshake with the proxied gemini server.
503 .It Ic use-tls Ar bool
504 Specify whether to use TLS when connecting to the proxied host.
506 .It Ic verifyname Ar bool
507 Enable or disable the TLS server name verification.
510 .It Ic root Ar directory
511 Specify the root directory for this server
512 .Pq alas the current Dq document root .
513 It's relative to the chroot if enabled.
514 .It Ic require Ic client Ic ca Ar path
515 Allow requests only from clients that provide a certificate signed by
516 the CA certificate in
518 It needs to be a PEM-encoded certificate and it's not relative to the
520 .It Ic strip Ar number
523 components from the beginning of the path before doing a lookup in the
525 It's also considered for the
527 parameter in the scope of a
533 section must include one or more lines of the following syntax, enclosed
536 .It Ar type Ns / Ns Ar subtype Ar name Op Ar name ...
541 to the specified extension
543 One or more names can be specified per line.
544 Earch line may end with an optional semicolon.
545 .It Ic include Ar file
546 Include types definition from an external file, for example
547 .Pa /usr/share/misc/mime.types .
552 uses the following mapping if no
556 .Bl -tag -offset indent -width 15m -compact
585 if no mapping was found.
587 The following is an example of a possible configuration for a site
588 that enables only TLSv1.3, adds the MIME types mapping from
589 .Pa /usr/share/misc/mime.types
590 and defines two virtual host:
591 .Bd -literal -offset indent
595 include "/usr/share/misc/mime.types"
598 server "example.com" {
599 listen on * port 1965
600 cert "/etc/ssl/example.com.pem"
601 key "/etc/ssl/private/example.com.key"
602 root "/var/gemini/example.com"
605 server "example.it" {
606 listen on * port 1965
607 cert "/etc/ssl/example.it.pem"
608 key "/etc/ssl/private/example.it.key"
609 root "/var/gemini/example.it"
611 # set the language for text/gemini files
616 Yet another example, showing how to enable a
621 .Bd -literal -offset indent
625 server "example.com" {
626 listen on * port 1965
629 cert "/etc/ssl/example.com.pem"
630 key "/etc/ssl/private/example.com.key"
632 # relative to the chroot:
635 location "/static/*" {
636 # load the following rules only for
637 # requests that matches "/static/*"
651 program was written by
652 .An Omar Polo Aq Mt op@omarpolo.com .
