1 .\" Copyright (c) 2021 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: January 30 2021$
19 .Nd simple and secure Gemini server
25 .Op Fl D Ar macro Ns = Ns Ar value
39 is a simple and minimal gemini server that can serve static files,
40 execute CGI scripts and talk to FastCGI applications.
41 It can run without a configuration file with a limited set of features
45 rereads the configuration file when it receives
48 The options are as follows:
51 Specify the configuration file.
52 .It Fl D Ar macro Ns = Ns Ar value
58 Overrides the definition of
60 in the config file if present.
62 Stays and logs on the foreground.
64 Check that the configuration is valid, but don't start the server.
68 pid to the given path.
71 If no configuration file is given,
73 will look for the following options
77 .It Fl d Pa certs-path
78 Directory where certificates for the config-less mode are stored.
80 .Pa $XDG_DATA_HOME/gmid ,
82 .Pa ~/.local/share/gmid .
84 The hostname, by default
86 Certificates for the given
88 are searched inside the
90 directory given with the
96 .Pa hostname.key.pem .
97 If a certificate or key don't exists for a given hostname they
98 will be automatically generated.
100 Print the usage and exit.
102 The port to listen on, by default 1965.
103 .It Fl V , Fl -version
104 Print the version and exit.
109 options increase the verbosity.
111 Enable execution of CGI scripts.
112 See the description of the
114 option in the section
119 Cannot be provided more than once.
121 The root directory to serve.
122 By default the current working directory is assumed.
124 .Sh CONFIGURATION FILE
125 The configuration file is divided into three sections:
128 User-defined variables may be defined and used later, simplifying the
130 .It Sy Global Options
134 Virtual hosts definition.
137 Within the sections, empty lines are ignored and comments can be put
138 anywhere in the file using a hash mark
140 and extend to the end of the current line.
141 A boolean is either the symbol
145 A string is a sequence of characters wrapped in double quotes,
147 Multiple strings one next to the other are joined into a single
149 .Bd -literal -offset indent
150 # equivalent to "temporary-failure"
151 block return 40 "temporary" "-" "failure"
154 Strict ordering of the sections is not enforced, so that is possible
155 to mix macros, options and
158 However, defining all the
160 blocks after the macros and the global options is recommended.
162 Macros can be defined that will later be expanded in context.
163 Macro names must start with a letter, digit or underscore and may
164 contain any of those characters.
165 Macros names may not be reserved words.
166 Macros are not expanded inside quotes.
169 .Bd -literal -offset indent
174 root $dir "/foo" # -> /var/gemini/foo
175 cert $cert "/foo.crt" # -> /etc/keys/foo.crt
176 key $cert "/foo.pem" # -> /etc/keys/foo.pem
181 .It Ic chroot Pa path
183 the process to the given
185 The daemon has to be run with root privileges and thus the option
187 needs to be provided, so privileges can be dropped.
190 will enter the chroot after loading the TLS keys, but before opening
191 the virtual host root directories.
192 It's recommended to keep the TLS keys outside the chroot.
197 Enable or disable IPv6 support.
199 .It Ic mime Ar mime-type Ar file-extension
200 Add a mapping for the given
204 Both argument are strings.
205 .It Ic port Ar portno
206 The port to listen on.
208 .It Ic prefork Ar number
209 Run the specified number of server processes.
210 This increases the performance and prevents delays when connecting to
213 runs 3 server processes by default, when not in config-less mode.
214 The maximum number allowed is 16.
215 .It Ic protocols Ar string
216 Specify the TLS protocols to enable.
218 .Xr tls_config_parse_protocols 3
219 for the valid protocol string values.
220 By default, both TLSv1.3 and TLSv1.2 are enabled.
223 to enable only TLSv1.3.
224 .It Ic user Ar string
225 Run the daemon as the given user.
228 Every virtual host is defined by a
232 .It Ic server Ar hostname Brq ...
233 Match the server name using shell globbing rules.
234 This can be an explicit name,
235 .Ar www.example.com ,
236 or a name including a wildcards,
240 Followed by a block of options that is enclosed in curly brackets:
243 Specify an additional alias
246 .It Ic auto Ic index Ar bool
247 If no index file is found, automatically generate a directory listing.
248 It's disabled by default.
249 .It Ic block Op Ic return Ar code Op Ar meta
250 Send a reply and close the connection;
256 .Dq temporary failure
260 is in the 3x range, then
265 the following special sequences are replaced:
266 .Bl -tag -width Ds -compact
268 is replaced with a single
271 is replaced with the request path.
273 is replaced with the query string of the request.
275 is replaced with the server port.
277 is replaced with the server name.
280 Path to the certificate to use for this server.
283 should contain a PEM encoded certificate.
284 This option is mandatory.
286 Execute CGI scripts that matches
288 using shell globbing rules.
289 .It Ic default type Ar string
290 Set the default media type that is used if the media type for a
291 specified extension is not found.
292 If not specified, the
295 .Dq application/octet-stream .
296 .It Ic entrypoint Pa path
297 Handle all the requests for the current virtual host using the
300 .It Ic env Ar name Ar value
301 Set the environment variable
305 when executing CGI scripts.
306 Can be provided more than once.
307 .\" don't document the "spawn <prog>" form because it probably won't
309 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Ar port Oc
310 Enable FastCGI instead of serving files.
313 can either be a UNIX domain socket or a TCP socket.
314 If the FastCGI application is listening on a UNIX domain socket,
316 is a local path name within the
322 keyword must be provided and
324 is interpreted as a hostname or an IP address.
326 can be either a port number or the name of a service enclosed in
328 If it's not specified defaults to 9000.
329 .It Ic index Ar string
330 Set the directory index file.
331 If not specified, it defaults to
334 Specify the private key to use for this server.
337 should contain a PEM encoded private key.
338 This option is mandatory.
339 .It Ic lang Ar string
340 Specify the language tag for the text/gemini content served.
343 parameter will be added in the response.
344 .It Ic location Pa path Brq ...
345 Specify server configuration rules for a specific location.
348 argument will be matched against the request path with shell globbing
350 In case of multiple location statements in the same context, the first
351 matching location will be put into effect and the later ones ignored.
352 Therefore is advisable to match for more specific paths first and for
353 generic ones later on.
356 section may include most of the server configuration rules
358 .Ic alias , Ic cert , Ic env , Ic key , Ic location ,
359 .Ic entrypoint No and Ic cgi .
361 Enable or disable the logging for the current server or location block.
362 .It Ic param Ar name Ar value
368 .It Ic root Pa directory
369 Specify the root directory for this server.
370 It's relative to the chroot, if enabled.
371 .It Ic require Ic client Ic ca Pa path
372 Allow requests only from clients that provide a certificate signed by
373 the CA certificate in
375 It needs to be a PEM-encoded certificate and it's not relative to the
377 .It Ic strip Ar number
380 components from the beginning of the path before doing a lookup in the
382 It's also considered for the
384 parameter in the scope of a
388 When a request for an executable file matches the
390 rule, that file will be execute and its output fed to the client.
392 The CGI scripts are executed in the directory they reside and inherit
395 with these additional variables set:
397 .It Ev GATEWAY_INTERFACE
399 .It Ev GEMINI_DOCUMENT_ROOT
400 The root directory of the virtual host.
401 .It Ev GEMINI_SCRIPT_FILENAME
402 Full path to the CGI script being executed.
404 The full IRI of the request.
405 .It Ev GEMINI_URL_PATH
406 The path of the request.
408 The portion of the requested path that is derived from the the IRI
409 path hierarchy following the part that identifies the script itself.
411 .It Ev PATH_TRANSLATED
412 Present if and only if
415 It represent the translation of the
418 builds this by appending the
420 to the virtual host directory root.
422 The decoded query string.
423 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
424 Textual representation of the client IP.
425 .It Ev REQUEST_METHOD
426 This is present only for RFC3875 (CGI) compliance.
427 It's always set to the empty string.
431 that identifies the current CGI script.
433 The name of the server
435 The port the server is listening on.
436 .It Ev SERVER_PROTOCOL
438 .It Ev SERVER_SOFTWARE
439 The name and version of the server, i.e.
442 The string "Certificate" if the client used a certificate, otherwise
445 The subject of the client certificate if provided, otherwise unset.
446 .It Ev TLS_CLIENT_ISSUER
447 The is the issuer of the client certificate if provided, otherwise
449 .It Ev TLS_CLIENT_HASH
450 The hash of the client certificate if provided, otherwise unset.
454 The TLS version negotiated with the peer.
456 The cipher suite negotiated with the peer.
457 .It Ev TLS_CIPHER_STRENGTH
458 The strength in bits for the symmetric cipher that is being used with
460 .It Ev TLS_CLIENT_NOT_AFTER
461 The time corresponding to the end of the validity period of the peer
462 certificate in the ISO 8601 format
463 .Pq e.g. Dq 2021-02-07T20:17:41Z .
464 .It Ev TLS_CLIENT_NOT_BEFORE
465 The time corresponding to the start of the validity period of the peer
466 certificate in the ISO 8601 format.
470 optionally supports FastCGI.
473 rule must be present in a server or location block.
474 Then, all requests matching that server or location will be handled
475 via the specified FastCGI backend.
477 By default the following variables
479 are sent, and carry the same semantics as with CGI.
480 More parameters can be added with the
517 TLS_CLIENT_NOT_BEFORE
522 To auto-detect the MIME type of the response
524 looks at the file extension and consults its internal table.
525 By default the following mappings are loaded, but they can be
526 overridden or extended using the
528 configuration option.
529 If no MIME is found, the value of
533 will be used, which is
534 .Dq application/octet-stream
537 .Bl -tag -offset indent -width 14m -compact
564 Serve the current directory
565 .Bd -literal -offset indent
569 To serve the directory
571 and enable CGI scripts inside
574 .Bd -literal -offset indent
576 $ cat <<EOF > docs/cgi/hello
578 printf "20 text/plain\\r\\n"
581 $ chmod +x docs/cgi/hello
582 $ gmid -x '/cgi/*' docs
585 The following is an example of a possible configuration for a site
586 that enables only TLSv1.3, adds a mime type for the file extension
587 "rtf" and defines two virtual host:
588 .Bd -literal -offset indent
589 ipv6 on # enable ipv6
593 mime "application/rtf" "rtf"
595 server "example.com" {
596 cert "/path/to/cert.pem"
597 key "/path/to/key.pem"
598 root "/var/gemini/example.com"
601 server "it.example.com" {
602 cert "/path/to/cert.pem"
603 key "/path/to/key.pem"
604 root "/var/gemini/it.example.com"
610 Yet another example, showing how to enable a
615 .Bd -literal -offset indent
619 server "example.com" {
620 cert "/path/to/cert.pem"
621 key "/path/to/key.pem"
622 root "/example.com" # in the /var/gemini chroot
624 location "/static/*" {
633 .Dq Flexible and Economical
634 UTF-8 decoder written by
635 .An Bjoern Hoehrmann .
640 program was written by
641 .An Omar Polo Aq Mt op@omarpolo.com .
645 The root directories of all virtual hosts are opened during the daemon
646 startup; this means that if a root directory gets deleted and then
649 won't be able to serve files inside that directory until a restart.
650 This restriction applies only to the root directories and not their content.
652 a %2F sequence is indistinguishable from a literal slash: this is not
655 a %00 sequence is treated as invalid character and thus rejected.
