1 .\" Copyright (c) 2022 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.
14 .Dd $Mdocdate: December 2 2022$
19 .Nd gmid Gemini server configuration file
22 is the configuration file format for the
26 The configuration file is divided into three 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, so privileges can be dropped.
124 will enter the chroot after loading the TLS keys, but before opening
125 the virtual host root directories.
126 It's recommended to keep the TLS keys outside the chroot.
131 Enable or disable IPv6 support, off by default.
132 .It Ic port Ar portno
133 The port to listen on.
135 .It Ic prefork Ar number
136 Run the specified number of server processes.
137 This increases the performance and prevents delays when connecting to
139 When not in config-less mode,
141 runs 3 server processes by default.
142 The maximum number allowed is 16.
143 .It Ic protocols Ar string
144 Specify the TLS protocols to enable.
146 .Xr tls_config_parse_protocols 3
147 for the valid protocol string values.
148 By default, both TLSv1.3 and TLSv1.2 are enabled.
151 to enable only TLSv1.3.
152 .It Ic user Ar string
153 Run the daemon as the given user.
156 Every virtual host is defined by a
160 .It Ic server Ar hostname Brq ...
161 Match the server name using shell globbing rules.
162 It can be an explicit name,
163 .Ar www.example.com ,
164 or a name including a wildcards,
168 Followed by a block of options that is enclosed in curly brackets:
171 Specify an additional alias
174 .It Ic auto Ic index Ar bool
175 If no index file is found, automatically generate a directory listing.
177 .It Ic block Op Ic return Ar code Op Ar meta
178 Send a reply and close the connection;
185 .Dq temporary failure .
188 is in the 3x range, then
193 the following special sequences are supported:
194 .Bl -tag -width Ds -compact
196 is replaced with a single
199 is replaced with the request path.
201 is replaced with the query string of the request.
203 is replaced with the server port.
205 is replaced with the server name.
208 Path to the certificate to use for this server.
210 should contain a PEM encoded certificate.
211 This option is mandatory.
217 using shell globbing rules.
219 The CGI scripts are executed in the directory they reside and inherit
222 with these additional variables set:
224 .It Ev GATEWAY_INTERFACE
226 .It Ev GEMINI_DOCUMENT_ROOT
227 The root directory of the virtual host.
228 .It Ev GEMINI_SCRIPT_FILENAME
229 Full path to the CGI script being executed.
231 The full IRI of the request.
232 .It Ev GEMINI_URL_PATH
233 The path of the request.
234 .It Ev GEMINI_SEARCH_STRING
237 if defined in the request and if it doesn't contain any unencoded
239 characters, otherwise unset.
241 The portion of the requested path that is derived from the the IRI
242 path hierarchy following the part that identifies the script itself.
244 .It Ev PATH_TRANSLATED
245 Present if and only if
248 It represent the translation of the
251 builds this by appending the
253 to the virtual host directory root.
255 The URL-encoded search or parameter string.
256 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
257 Textual representation of the client IP.
258 .It Ev REQUEST_METHOD
259 This is present only for RFC3875 (CGI) compliance.
260 It's always set to the empty string.
264 that identifies the current CGI script.
266 The name of the server
268 The port the server is listening on.
269 .It Ev SERVER_PROTOCOL
271 .It Ev SERVER_SOFTWARE
272 The name and version of the server, i.e.
275 The string "Certificate" if the client used a certificate, otherwise
278 The subject of the client certificate if provided, otherwise unset.
279 .It Ev TLS_CLIENT_ISSUER
280 The is the issuer of the client certificate if provided, otherwise
282 .It Ev TLS_CLIENT_HASH
283 The hash of the client certificate if provided, otherwise unset.
287 The TLS version negotiated with the peer.
289 The cipher suite negotiated with the peer.
290 .It Ev TLS_CIPHER_STRENGTH
291 The strength in bits for the symmetric cipher that is being used with
293 .It Ev TLS_CLIENT_NOT_AFTER
294 The time corresponding to the end of the validity period of the peer
295 certificate in the ISO 8601 format
296 .Pq e.g. Dq 2021-02-07T20:17:41Z .
297 .It Ev TLS_CLIENT_NOT_BEFORE
298 The time corresponding to the start of the validity period of the peer
299 certificate in the ISO 8601 format.
301 .It Ic default type Ar string
302 Set the default media type that is used if the media type for a
303 specified extension is not found.
304 If not specified, the
307 .Dq application/octet-stream .
308 .It Ic entrypoint Ar path
309 Handle all the requests for the current virtual host using the
313 relative to the current document root.
314 .It Ic env Ar name Cm = Ar value
315 Set the environment variable
319 when executing CGI scripts.
320 Can be provided more than once.
321 .\" don't document the "spawn <prog>" form because it probably won't
323 .It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
326 instead of serving files.
329 can either be a UNIX-domain socket or a TCP socket.
330 If the FastCGI application is listening on a UNIX domain socket,
332 is a local path name within the
338 keyword must be provided and
340 is interpreted as a hostname or an IP address.
342 can be either a port number or the name of a service enclosed in
344 If not specified defaults to 9000.
345 .It Ic index Ar string
346 Set the directory index file.
347 If not specified, it defaults to
350 Specify the private key to use for this server.
352 should contain a PEM encoded private key.
353 This option is mandatory.
354 .It Ic lang Ar string
355 Specify the language tag for the text/gemini content served.
358 parameter will be added in the response.
359 .It Ic location Ar path Brq ...
360 Specify server configuration rules for a specific location.
362 argument will be matched against the request path with shell globbing
364 In case of multiple location statements in the same context, the first
365 matching location will be put into effect and the later ones ignored.
366 Therefore is advisable to match for more specific paths first and for
367 generic ones later on.
370 section may include most of the server configuration rules
372 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
373 .Ic location , Ic param No and Ic proxy .
375 Enable or disable the logging for the current server or location block.
376 .It Ic param Ar name Cm = Ar value
382 By default the following variables
384 are sent, and carry the same semantics as with CGI:
420 TLS_CLIENT_NOT_BEFORE
425 Specify an OCSP response to be stapled during TLS handshakes
429 should contain a DER-format OCSP response retrieved from an
433 If the OCSP response in
435 is empty, OCSP stapling will not be used.
436 The default is to not use OCSP stapling.
437 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
438 Set up a reverse proxy.
439 The optional matching rules
443 can be used to enable proxying only for protocols matching
448 and/or whose request IRI matches
452 .Pq 1965 by default .
453 Matching happens using shell globbing rules.
455 In case of multiple matching proxy blocks in the same context, the
456 first matching proxy will be put into effect and the later ones
462 Specify the client certificate to use when making requests.
464 Specify the client certificate key to use when making requests.
465 .It Ic protocols Ar string
466 Specify the TLS protocols allowed when making remote requests.
468 .Xr tls_config_parse_protocols 3
469 function for the valid protocol string values.
470 By default, both TLSv1.2 and TLSv1.3 are enabled.
471 .It Ic relay-to Ar host : Ns Op Ar port
472 Relay the request to the given
477 This is the only mandatory option in a
480 .It Ic require Ic client Ic ca Ar file
481 Allow the proxying only from clients that provide a certificate
482 signed by the CA certificate in
484 .It Ic sni Ar hostname
487 instead of the one extracted from the
489 rule for the TLS handshake with the proxied gemini server.
490 .It Ic use-tls Ar bool
491 Specify whether to use TLS when connecting to the proxied host.
493 .It Ic verifyname Ar bool
494 Enable or disable the TLS server name verification.
497 .It Ic root Ar directory
498 Specify the root directory for this server
499 .Pq alas the current Dq document root .
500 It's relative to the chroot if enabled.
501 .It Ic require Ic client Ic ca Ar path
502 Allow requests only from clients that provide a certificate signed by
503 the CA certificate in
505 It needs to be a PEM-encoded certificate and it's not relative to the
507 .It Ic strip Ar number
510 components from the beginning of the path before doing a lookup in the
512 It's also considered for the
514 parameter in the scope of a
520 section must include one or more lines of the following syntax, enclosed
523 .It Ar type/subtype Ar name Op Ar name ...
528 to the specified extension
530 One or more names can be specified per line.
531 Earch line may end with an optional semicolon.
532 .It Ic include Ar file
533 Include types definition from an external file, for example
534 .Pa /usr/share/misc/mime.types .
539 uses the following mapping if no
542 .Bl -tag -offset indent -width 15m -compact
571 if no mapping was found.
573 The following is an example of a possible configuration for a site
574 that enables only TLSv1.3, adds the MIME types mapping from
575 .Pa /usr/share/misc/mime.types
576 and defines two virtual host:
577 .Bd -literal -offset indent
578 ipv6 on # enable ipv6
583 include "/usr/share/misc/mime.types"
586 server "example.com" {
587 cert "/etc/ssl/example.com.pem"
588 key "/etc/ssl/private/example.com.key"
589 root "/var/gemini/example.com"
592 server "example.it" {
593 cert "/etc/ssl/example.it.pem"
594 key "/etc/ssl/private/example.it.key"
595 root "/var/gemini/example.it"
597 # execute cgi scripts inside "cgi-bin"
600 # set the language for text/gemini files
605 Yet another example, showing how to enable a
610 .Bd -literal -offset indent
614 server "example.com" {
616 cert "/etc/ssl/example.com.pem"
617 key "/etc/ssl/private/example.com.key"
619 # relative to the chroot:
622 location "/static/*" {
623 # load the following rules only for
624 # requests that matches "/static/*"
638 program was written by
639 .An Omar Polo Aq Mt op@omarpolo.com .
