1 .\" Copyright (c) 2022, 2023, 2024 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 Media types and extensions.
37 Virtual hosts definition.
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
104 certdir = "/etc/keys"
105 common = "lang it; auto index on"
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"
117 .It Ic chroot Ar path
119 the process to the given
121 The daemon has to be run with root privileges and thus the option
123 needs to be provided too, so privileges can be dropped afterwards.
124 If enabled all the paths in the configuration file are relative to the
125 chroot directory, except for the
134 home directory, if provided.
135 .It Ic log Ar options
136 Specify logging options.
137 Multiple options may be provided within curly braces.
138 The available options are as follows:
140 .It Ic access Ar file
143 The path is not 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
178 .\" format since 2.0.
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 request,
183 .\" the size of the response, the response code and meta.
185 Each line is formatted as follows: the remote IP address and port, the
187 keyword, the request URI, the response code and meta.
189 .It Ic syslog Op Ic off
191 It is enabled by default, use the
194 .It Ic syslog facility Ar facility
199 Available facilities are as follows: daemon, ftp, local0 through local7 and
201 These are case insensitive and can be prefixed with
203 Not all level may be available on all operating systems.
204 The default facility is
207 .It Ic prefork Ar number
208 Run the specified number of server processes.
209 This increases the performance and prevents delays when connecting to
212 runs 3 server processes by default.
213 The maximum number allowed is 16.
214 .It Ic protocols Ar string
215 Specify the TLS protocols to enable.
217 .Xr tls_config_parse_protocols 3
218 for the valid protocol string values.
219 By default, both TLSv1.3 and TLSv1.2 are enabled.
222 to enable only TLSv1.3.
223 .It Ic user Ar string
224 Run the daemon as the given user.
230 Every virtual host is defined by a
234 .It Ic server Ar hostname Brq ...
235 Match the server name using shell globbing rules.
236 It can be an explicit name,
237 .Ar www.example.com ,
238 or a name including wildcards,
242 Followed by a block of options that is enclosed in curly brackets:
245 Specify an additional alias
248 .It Ic auto Ic index Ar bool
249 If no index file is found, automatically generate a directory listing.
251 .It Ic block Op Ic return Ar code Op Ar meta
252 Send a reply and close the connection;
259 .Dq temporary failure .
262 is in the 3x range, then
267 the following special sequences are supported:
268 .Bl -tag -width Ds -compact
270 is replaced with a single
273 is replaced with the request path.
275 is replaced with the query string of the request.
277 is replaced with the server port.
279 is replaced with the server name.
282 Path to the certificate to use for this server.
284 should contain a PEM encoded certificate.
285 This option is mandatory.
286 .It Ic default type Ar string
287 Set the default media type that is used if the media type for a
288 specified extension is not found.
289 If not specified, the
292 .Dq application/octet-stream .
293 .It Ic fastcgi Ar option
294 Enable FastCGI instead of serving files.
295 Multiple options may be specified within curly braces.
298 .It Ic param Ar name Cm = Ar value
303 .It Ic socket Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
306 can either be a UNIX-domain socket or a TCP socket.
307 If the FastCGI application is listening on a UNIX domain socket,
309 is a local path name within the
315 keyword must be provided and
317 is interpreted as a hostname or an IP address.
319 can be either a port number or the name of a service enclosed in
321 If not specified defaults to 9000.
322 .It Ic strip Ar number
325 leading path components from the request URL before splitting it in
331 The FastCGI handler will be given the following variables by default:
333 .\" .It Ev GEMINI_DOCUMENT_ROOT
334 .\" The root directory of the virtual host.
335 .It Ev GEMINI_URL_PATH
336 Full path of the request.
337 .It Ev GEMINI_SEARCH_STRING
340 if defined in the request and if it doesn't contain any unencoded
342 characters, otherwise unset.
343 .It Ev GATEWAY_INTERFACE
346 The string "Certificate" if the client used a certificate, otherwise
349 The portion of the requested path that is derived from the the IRI
350 path hierarchy following
353 .It Ev PATH_TRANSLATED
354 Present if and only if
357 It represent the translation of the
360 builds this by appending the
362 to the virtual host directory root.
364 The URL-encoded search or parameter string.
365 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
366 Textual representation of the client IP.
367 .It Ev REQUEST_METHOD
368 This is present only for RFC3875 (CGI) compliance.
372 The virtual URI path to the script.
373 Since it's impossible to determine in all cases the correct
377 assumes it's the empty string.
378 It is recommended to manually specify this parameter when serving a
379 sub-tree of a virtual host via FastCGI.
381 The name of the server
383 The port the server is listening on.
384 .It Ev SERVER_PROTOCOL
386 .It Ev SERVER_SOFTWARE
387 The name and version of the server, i.e.
390 The subject of the client certificate if provided, otherwise unset.
391 .It Ev TLS_CLIENT_ISSUER
392 The is the issuer of the client certificate if provided, otherwise
394 .It Ev TLS_CLIENT_HASH
395 The hash of the client certificate if provided, otherwise unset.
399 The TLS version negotiated with the peer.
401 The cipher suite negotiated with the peer.
402 .It Ev TLS_CIPHER_STRENGTH
403 The strength in bits for the symmetric cipher that is being used with
405 .It Ev TLS_CLIENT_NOT_AFTER
406 The time corresponding to the end of the validity period of the peer
407 certificate in the ISO 8601 format
408 .Pq e.g. Dq 2021-02-07T20:17:41Z .
409 .It Ev TLS_CLIENT_NOT_BEFORE
410 The time corresponding to the start of the validity period of the peer
411 certificate in the ISO 8601 format.
414 Disable FastCGI handling in the current location.
415 .It Ic index Ar string
416 Set the directory index file.
417 If not specified, it defaults to
420 Specify the private key to use for this server.
422 should contain a PEM encoded private key.
423 This option is mandatory.
424 .It Ic lang Ar string
425 Specify the language tag for the text/gemini content served.
428 parameter will be added in the response.
429 .It Ic listen on Ar address Op Ic port Ar number
436 This statement can be specified multiple times.
443 will listen on all IPv4 and IPv6 addresses.
445 can be used to listen on all IPv4 addresses and
447 on all IPv6 addresses.
448 .It Ic location Ar path Brq ...
449 Specify server configuration rules for a specific location.
451 argument will be matched against the request path with shell globbing
453 In case of multiple location statements in the same context, the first
454 matching location will be put into effect and the later ones ignored.
455 Therefore is advisable to match for more specific paths first and for
456 generic ones later on.
459 section may include most of the server configuration rules
461 .Ic alias , Ic cert , Ic key , Ic listen , Ic location
465 Enable or disable the logging for the current server or location block.
467 Specify an OCSP response to be stapled during TLS handshakes
471 should contain a DER-format OCSP response retrieved from an
475 If the OCSP response in
477 is empty, OCSP stapling will not be used.
478 The default is to not use OCSP stapling.
479 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host Oo Cm port Ar port Oc Oc Brq ...
480 Set up a reverse proxy.
481 The optional matching rules
485 can be used to enable proxying only for protocols matching
490 and/or whose request IRI matches
494 .Pq 1965 by default .
495 Matching happens using shell globbing rules.
497 In case of multiple matching proxy blocks in the same context, the
498 first matching proxy will be put into effect and the later ones
504 Specify the client certificate to use when making requests.
506 Specify the client certificate key to use when making requests.
507 .It Ic protocols Ar string
508 Specify the TLS protocols allowed when making remote requests.
510 .Xr tls_config_parse_protocols 3
511 function for the valid protocol string values.
512 By default, both TLSv1.2 and TLSv1.3 are enabled.
513 .It Ic relay-to Ar host Op Cm port Ar port
514 Relay the request to the given
519 This is the only mandatory option in a
522 .It Ic require Ic client Ic ca Ar file
523 Allow the proxying only from clients that provide a certificate
524 signed by the CA certificate in
526 .It Ic sni Ar hostname
529 instead of the one extracted from the
531 rule for the TLS handshake with the proxied gemini server.
532 .It Ic use-tls Ar bool
533 Specify whether to use TLS when connecting to the proxied host.
535 .It Ic verifyname Ar bool
536 Enable or disable the TLS server name verification.
539 .It Ic root Ar directory
540 Specify the root directory for this server
541 .Pq alas the current Dq document root .
542 It's relative to the chroot if enabled.
543 .It Ic require Ic client Ic ca Ar path
544 Allow requests only from clients that provide a certificate signed by
545 the CA certificate in
547 It needs to be a PEM-encoded certificate and it's not relative to the
549 .It Ic strip Ar number
552 components from the beginning of the path before doing a lookup in the
554 It's also considered for the
556 parameter in the scope of a
562 section must include one or more lines of the following syntax, enclosed
565 .It Ar type Ns / Ns Ar subtype Ar name Op Ar name ...
570 to the specified extension
572 One or more names can be specified per line.
573 Earch line may end with an optional semicolon.
574 .It Ic include Ar file
575 Include types definition from an external file, for example
576 .Pa /usr/share/misc/mime.types .
581 uses the following mapping if no
585 .Bl -tag -offset indent -width 15m -compact
614 if no mapping was found.
616 The following is an example of a possible configuration for a site
617 that enables only TLSv1.3, adds the MIME types mapping from
618 .Pa /usr/share/misc/mime.types
619 and defines two virtual host:
620 .Bd -literal -offset indent
624 include "/usr/share/misc/mime.types"
627 server "example.com" {
628 listen on * port 1965
629 cert "/etc/ssl/example.com.pem"
630 key "/etc/ssl/private/example.com.key"
631 root "/var/gemini/example.com"
634 server "example.it" {
635 listen on * port 1965
636 cert "/etc/ssl/example.it.pem"
637 key "/etc/ssl/private/example.it.key"
638 root "/var/gemini/example.it"
640 # set the language for text/gemini files
645 Yet another example, showing how to enable a
650 .Bd -literal -offset indent
654 server "example.com" {
655 listen on * port 1965
658 cert "/etc/ssl/example.com.pem"
659 key "/etc/ssl/private/example.com.key"
661 # relative to the chroot:
664 location "/static/*" {
665 # load the following rules only for
666 # requests that matches "/static/*"
674 This shows how to set up a reverse proxy: all request for
676 will be forwarded to 10.0.0.6 transparently.
677 Proxying establish a new TLS connection, so any client-certificates used
680 cannot be provided to the proxied server as well.
681 .Bd -literal -offset indent
682 server "example.com" {
683 listen on * port 1965
684 cert "/etc/ssl/example.com.pem"
685 key "/etc/ssl/private/example.com.key"
687 relay-to 10.0.0.6 port 1965
698 program was written by
699 .An Omar Polo Aq Mt op@omarpolo.com .
