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:
139 This is the default behaviour.
140 .It Ic access Ar file
143 The path is relative to the
145 .It Ic style Ar style
146 Set the logging style, defaults to
153 Attempt to be compatible with the default Apache httpd log format.
154 Each line is formatted as follows: the matching host name,
155 the remote IP address, one dash
157 Common Name of the client certificate
158 .Pq if provided, '-' otherwise ,
159 the timestamp of the request, the request URI wrapped in double quotes,
160 the response code and the size of the response.
162 Attempt to be compatible with the default nginx log format.
163 Each line is formatted as follows: the remote IP address, one dash
165 Common Name of the client certificate
166 .Pq if provided, '-' otherwise ,
167 the timestamp wrapped in square brackets, the request URI wrapped in
168 double quotes, the response code, the size of the response, a dash
169 wrapped in double quotes and "".
170 The strangness of these two last fields is because Gemini doesn't have
179 Each line is formatted as follows: RFC 3339 date time,
180 remote IP address, Common Name of the client certificate
181 .Pq if provided, '-' otherwise ,
182 the matching host name, the request URI, the size of the response,
183 the response code and meta.
185 The pre-2.0 gmid native format.
186 Each line is formatted as follows: the remote IP address and port, the
188 keyword, the request URI, the response code and meta.
191 .It Ic prefork Ar number
192 Run the specified number of server processes.
193 This increases the performance and prevents delays when connecting to
196 runs 3 server processes by default.
197 The maximum number allowed is 16.
198 .It Ic protocols Ar string
199 Specify the TLS protocols to enable.
201 .Xr tls_config_parse_protocols 3
202 for the valid protocol string values.
203 By default, both TLSv1.3 and TLSv1.2 are enabled.
206 to enable only TLSv1.3.
207 .It Ic user Ar string
208 Run the daemon as the given user.
211 Every virtual host is defined by a
215 .It Ic server Ar hostname Brq ...
216 Match the server name using shell globbing rules.
217 It can be an explicit name,
218 .Ar www.example.com ,
219 or a name including a wildcards,
223 Followed by a block of options that is enclosed in curly brackets:
226 Specify an additional alias
229 .It Ic auto Ic index Ar bool
230 If no index file is found, automatically generate a directory listing.
232 .It Ic block Op Ic return Ar code Op Ar meta
233 Send a reply and close the connection;
240 .Dq temporary failure .
243 is in the 3x range, then
248 the following special sequences are supported:
249 .Bl -tag -width Ds -compact
251 is replaced with a single
254 is replaced with the request path.
256 is replaced with the query string of the request.
258 is replaced with the server port.
260 is replaced with the server name.
263 Path to the certificate to use for this server.
265 should contain a PEM encoded certificate.
266 This option is mandatory.
267 .It Ic default type Ar string
268 Set the default media type that is used if the media type for a
269 specified extension is not found.
270 If not specified, the
273 .Dq application/octet-stream .
274 .It Ic fastcgi Ar option
275 Enable FastCGI instead of serving files.
276 Multiple options may be specified within curly braces.
279 .It Ic param Ar name Cm = Ar value
284 .It Ic socket Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
287 can either be a UNIX-domain socket or a TCP socket.
288 If the FastCGI application is listening on a UNIX domain socket,
290 is a local path name within the
296 keyword must be provided and
298 is interpreted as a hostname or an IP address.
300 can be either a port number or the name of a service enclosed in
302 If not specified defaults to 9000.
305 The FastCGI handler will be given the following variables by default:
307 .It Ev GATEWAY_INTERFACE
309 .It Ev GEMINI_DOCUMENT_ROOT
310 The root directory of the virtual host.
311 .It Ev GEMINI_SCRIPT_FILENAME
312 Full path to the FastCGI script being executed.
314 The full IRI of the request.
315 .It Ev GEMINI_URL_PATH
316 The path of the request.
317 .It Ev GEMINI_SEARCH_STRING
320 if defined in the request and if it doesn't contain any unencoded
322 characters, otherwise unset.
324 The portion of the requested path that is derived from the the IRI
325 path hierarchy following the part that identifies the script itself.
327 .It Ev PATH_TRANSLATED
328 Present if and only if
331 It represent the translation of the
334 builds this by appending the
336 to the virtual host directory root.
338 The URL-encoded search or parameter string.
339 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
340 Textual representation of the client IP.
341 .It Ev REQUEST_METHOD
342 This is present only for RFC3875 (CGI) compliance.
343 It's always set to the empty string.
345 The virtual URI path to the script.
347 The name of the server
349 The port the server is listening on.
350 .It Ev SERVER_PROTOCOL
352 .It Ev SERVER_SOFTWARE
353 The name and version of the server, i.e.
356 The string "Certificate" if the client used a certificate, otherwise
359 The subject of the client certificate if provided, otherwise unset.
360 .It Ev TLS_CLIENT_ISSUER
361 The is the issuer of the client certificate if provided, otherwise
363 .It Ev TLS_CLIENT_HASH
364 The hash of the client certificate if provided, otherwise unset.
368 The TLS version negotiated with the peer.
370 The cipher suite negotiated with the peer.
371 .It Ev TLS_CIPHER_STRENGTH
372 The strength in bits for the symmetric cipher that is being used with
374 .It Ev TLS_CLIENT_NOT_AFTER
375 The time corresponding to the end of the validity period of the peer
376 certificate in the ISO 8601 format
377 .Pq e.g. Dq 2021-02-07T20:17:41Z .
378 .It Ev TLS_CLIENT_NOT_BEFORE
379 The time corresponding to the start of the validity period of the peer
380 certificate in the ISO 8601 format.
383 Disable FastCGI handling in the current location.
384 .It Ic index Ar string
385 Set the directory index file.
386 If not specified, it defaults to
389 Specify the private key to use for this server.
391 should contain a PEM encoded private key.
392 This option is mandatory.
393 .It Ic lang Ar string
394 Specify the language tag for the text/gemini content served.
397 parameter will be added in the response.
398 .It Ic listen on Ar address Op Ic port Ar number
405 This statement can be specified multiple times.
412 will listen on all IPv4 and IPv6 addresses.
414 can be used to listen on all IPv4 addresses and
416 on all IPv6 addresses.
417 .It Ic location Ar path Brq ...
418 Specify server configuration rules for a specific location.
420 argument will be matched against the request path with shell globbing
422 In case of multiple location statements in the same context, the first
423 matching location will be put into effect and the later ones ignored.
424 Therefore is advisable to match for more specific paths first and for
425 generic ones later on.
428 section may include most of the server configuration rules
430 .Ic alias , Ic cert , Ic key , Ic listen , Ic location
434 Enable or disable the logging for the current server or location block.
436 Specify an OCSP response to be stapled during TLS handshakes
440 should contain a DER-format OCSP response retrieved from an
444 If the OCSP response in
446 is empty, OCSP stapling will not be used.
447 The default is to not use OCSP stapling.
448 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host Oo Cm port Ar port Oc Oc Brq ...
449 Set up a reverse proxy.
450 The optional matching rules
454 can be used to enable proxying only for protocols matching
459 and/or whose request IRI matches
463 .Pq 1965 by default .
464 Matching happens using shell globbing rules.
466 In case of multiple matching proxy blocks in the same context, the
467 first matching proxy will be put into effect and the later ones
473 Specify the client certificate to use when making requests.
475 Specify the client certificate key to use when making requests.
476 .It Ic protocols Ar string
477 Specify the TLS protocols allowed when making remote requests.
479 .Xr tls_config_parse_protocols 3
480 function for the valid protocol string values.
481 By default, both TLSv1.2 and TLSv1.3 are enabled.
482 .It Ic relay-to Ar host Op Cm port Ar port
483 Relay the request to the given
488 This is the only mandatory option in a
491 .It Ic require Ic client Ic ca Ar file
492 Allow the proxying only from clients that provide a certificate
493 signed by the CA certificate in
495 .It Ic sni Ar hostname
498 instead of the one extracted from the
500 rule for the TLS handshake with the proxied gemini server.
501 .It Ic use-tls Ar bool
502 Specify whether to use TLS when connecting to the proxied host.
504 .It Ic verifyname Ar bool
505 Enable or disable the TLS server name verification.
508 .It Ic root Ar directory
509 Specify the root directory for this server
510 .Pq alas the current Dq document root .
511 It's relative to the chroot if enabled.
512 .It Ic require Ic client Ic ca Ar path
513 Allow requests only from clients that provide a certificate signed by
514 the CA certificate in
516 It needs to be a PEM-encoded certificate and it's not relative to the
518 .It Ic strip Ar number
521 components from the beginning of the path before doing a lookup in the
523 It's also considered for the
525 parameter in the scope of a
531 section must include one or more lines of the following syntax, enclosed
534 .It Ar type Ns / Ns Ar subtype Ar name Op Ar name ...
539 to the specified extension
541 One or more names can be specified per line.
542 Earch line may end with an optional semicolon.
543 .It Ic include Ar file
544 Include types definition from an external file, for example
545 .Pa /usr/share/misc/mime.types .
550 uses the following mapping if no
554 .Bl -tag -offset indent -width 15m -compact
583 if no mapping was found.
585 The following is an example of a possible configuration for a site
586 that enables only TLSv1.3, adds the MIME types mapping from
587 .Pa /usr/share/misc/mime.types
588 and defines two virtual host:
589 .Bd -literal -offset indent
593 include "/usr/share/misc/mime.types"
596 server "example.com" {
597 listen on * port 1965
598 cert "/etc/ssl/example.com.pem"
599 key "/etc/ssl/private/example.com.key"
600 root "/var/gemini/example.com"
603 server "example.it" {
604 listen on * port 1965
605 cert "/etc/ssl/example.it.pem"
606 key "/etc/ssl/private/example.it.key"
607 root "/var/gemini/example.it"
609 # set the language for text/gemini files
614 Yet another example, showing how to enable a
619 .Bd -literal -offset indent
623 server "example.com" {
624 listen on * port 1965
627 cert "/etc/ssl/example.com.pem"
628 key "/etc/ssl/private/example.com.key"
630 # relative to the chroot:
633 location "/static/*" {
634 # load the following rules only for
635 # requests that matches "/static/*"
649 program was written by
650 .An Omar Polo Aq Mt op@omarpolo.com .
