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: July 29 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.
65 If specified two or more time, dump the configuration in addition to
68 Write daemon's pid to the given location.
70 will also act as lock: if another process is holding a lock on that
76 If no configuration file is given,
78 will look for the following options
82 .It Fl d Pa certs-path
83 Directory where certificates for the config-less mode are stored.
85 .Pa $XDG_DATA_HOME/gmid ,
87 .Pa ~/.local/share/gmid .
94 Certificates for the given
96 are searched inside the
98 directory given with the
102 .Pa hostname.cert.pem
104 .Pa hostname.key.pem .
105 If a certificate or a key doesn't exist for a given hostname, they
106 will be generated automatically.
108 Print the usage and exit.
110 The port to listen on, by default 1965.
111 .It Fl V , Fl -version
112 Print the version and exit.
117 options increase the verbosity.
122 See the description of the
126 section below to learn how
129 Cannot be provided more than once.
131 The root directory to serve.
132 By default the current working directory is assumed.
134 .Sh CONFIGURATION FILE
135 The configuration file is divided into three sections:
138 User-defined variables may be defined and used later, simplifying the
140 .It Sy Global Options
144 Virtual hosts definition.
147 Within the sections, empty lines are ignored and comments can be put
148 anywhere in the file using a hash mark
150 and extend to the end of the current line.
151 A boolean is either the symbol
155 A string is a sequence of characters wrapped in double quotes,
157 Multiple strings one next to the other are joined into a single
159 .Bd -literal -offset indent
160 # equivalent to "temporary-failure"
161 block return 40 "temporary" "-" "failure"
164 Furthermore, quoting is necessary only when a string needs to contain
166 .Pq like spaces or punctuation ,
167 something that looks like a number or a reserved keyword.
168 The last example could have been written also as:
169 .Bd -literal -offset indent
170 block return 40 temporary "-" failure
173 Strict ordering of the sections is not enforced, so that is possible
174 to mix macros, options and
177 However, defining all the
179 blocks after the macros and the global options is recommended.
181 Newlines are often optional, except around top-level instructions, and
184 can also be optionally used to separate options.
186 Additional configuration files can be included with the
188 keyword, for example:
189 .Bd -literal -offset indent
190 include "/etc/gmid.conf.local"
193 Macros can be defined that will later be expanded in context.
194 Macro names must start with a letter, digit or underscore and may
195 contain any of those characters.
196 Macros names may not be reserved words.
197 Macros are not expanded inside quotes.
199 Two kinds of macros are supported: variable-like and proper macros.
200 When a macro is invoked with a
202 before its name its expanded as a string, whereas when it's invoked
205 its expanded in-place.
208 .Bd -literal -offset indent
210 certdir = "/etc/keys"
211 common = "lang it; auto index on"
214 root $dir "/foo" # -> /var/gemini/foo
215 cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
216 key $certdir "/foo.pem" # -> /etc/keys/foo.pem
222 .It Ic chroot Pa path
224 the process to the given
226 The daemon has to be run with root privileges and thus the option
228 needs to be provided, so privileges can be dropped.
231 will enter the chroot after loading the TLS keys, but before opening
232 the virtual host root directories.
233 It's recommended to keep the TLS keys outside the chroot.
238 Enable or disable IPv6 support, off by default.
239 .It Ic map Ar mime-type Cm to-ext Ar file-extension
244 Both argument are strings.
245 .It Ic port Ar portno
246 The port to listen on.
248 .It Ic prefork Ar number
249 Run the specified number of server processes.
250 This increases the performance and prevents delays when connecting to
252 When not in config-less mode,
254 runs 3 server processes by default.
255 The maximum number allowed is 16.
256 .It Ic protocols Ar string
257 Specify the TLS protocols to enable.
259 .Xr tls_config_parse_protocols 3
260 for the valid protocol string values.
261 By default, both TLSv1.3 and TLSv1.2 are enabled.
264 to enable only TLSv1.3.
265 .It Ic user Ar string
266 Run the daemon as the given user.
269 Every virtual host is defined by a
273 .It Ic server Ar hostname Brq ...
274 Match the server name using shell globbing rules.
275 It can be an explicit name,
276 .Ar www.example.com ,
277 or a name including a wildcards,
281 Followed by a block of options that is enclosed in curly brackets:
284 Specify an additional alias
287 .It Ic auto Ic index Ar bool
288 If no index file is found, automatically generate a directory listing.
290 .It Ic block Op Ic return Ar code Op Ar meta
291 Send a reply and close the connection;
298 .Dq temporary failure .
301 is in the 3x range, then
306 the following special sequences are supported:
307 .Bl -tag -width Ds -compact
309 is replaced with a single
312 is replaced with the request path.
314 is replaced with the query string of the request.
316 is replaced with the server port.
318 is replaced with the server name.
321 Path to the certificate to use for this server.
324 should contain a PEM encoded certificate.
325 This option is mandatory.
331 using shell globbing rules.
332 .It Ic default type Ar string
333 Set the default media type that is used if the media type for a
334 specified extension is not found.
335 If not specified, the
338 .Dq application/octet-stream .
339 .It Ic entrypoint Pa path
340 Handle all the requests for the current virtual host using the
344 relative to the current document root.
345 .It Ic env Ar name Cm = Ar value
346 Set the environment variable
350 when executing CGI scripts.
351 Can be provided more than once.
352 .\" don't document the "spawn <prog>" form because it probably won't
354 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
357 instead of serving files.
360 can either be a UNIX-domain socket or a TCP socket.
361 If the FastCGI application is listening on a UNIX domain socket,
363 is a local path name within the
369 keyword must be provided and
371 is interpreted as a hostname or an IP address.
373 can be either a port number or the name of a service enclosed in
375 If not specified defaults to 9000.
376 .It Ic index Ar string
377 Set the directory index file.
378 If not specified, it defaults to
381 Specify the private key to use for this server.
384 should contain a PEM encoded private key.
385 This option is mandatory.
386 .It Ic lang Ar string
387 Specify the language tag for the text/gemini content served.
390 parameter will be added in the response.
391 .It Ic location Pa path Brq ...
392 Specify server configuration rules for a specific location.
395 argument will be matched against the request path with shell globbing
397 In case of multiple location statements in the same context, the first
398 matching location will be put into effect and the later ones ignored.
399 Therefore is advisable to match for more specific paths first and for
400 generic ones later on.
403 section may include most of the server configuration rules
405 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
406 .Ic location No and Ic param .
408 Enable or disable the logging for the current server or location block.
409 .It Ic param Ar name Cm = Ar value
416 Specify an OCSP response to be stapled during TLS handshakes
420 should contain a DER-format OCSP response retrieved from an
424 If the OCSP response in
426 is empty, OCSP stapling will not be used.
427 The default is to not use OCSP stapling.
428 .It Ic root Pa directory
429 Specify the root directory for this server
430 .Pq alas the current Dq document root .
431 It's relative to the chroot if enabled.
432 .It Ic require Ic client Ic ca Pa path
433 Allow requests only from clients that provide a certificate signed by
434 the CA certificate in
436 It needs to be a PEM-encoded certificate and it's not relative to the
438 .It Ic strip Ar number
441 components from the beginning of the path before doing a lookup in the
443 It's also considered for the
445 parameter in the scope of a
449 When a request for an executable file matches the
451 rule, that file will be executed and its output fed to the client.
453 The CGI scripts are executed in the directory they reside and inherit
456 with these additional variables set:
458 .It Ev GATEWAY_INTERFACE
460 .It Ev GEMINI_DOCUMENT_ROOT
461 The root directory of the virtual host.
462 .It Ev GEMINI_SCRIPT_FILENAME
463 Full path to the CGI script being executed.
465 The full IRI of the request.
466 .It Ev GEMINI_URL_PATH
467 The path of the request.
469 The portion of the requested path that is derived from the the IRI
470 path hierarchy following the part that identifies the script itself.
472 .It Ev PATH_TRANSLATED
473 Present if and only if
476 It represent the translation of the
479 builds this by appending the
481 to the virtual host directory root.
483 The decoded query string.
484 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
485 Textual representation of the client IP.
486 .It Ev REQUEST_METHOD
487 This is present only for RFC3875 (CGI) compliance.
488 It's always set to the empty string.
492 that identifies the current CGI script.
494 The name of the server
496 The port the server is listening on.
497 .It Ev SERVER_PROTOCOL
499 .It Ev SERVER_SOFTWARE
500 The name and version of the server, i.e.
503 The string "Certificate" if the client used a certificate, otherwise
506 The subject of the client certificate if provided, otherwise unset.
507 .It Ev TLS_CLIENT_ISSUER
508 The is the issuer of the client certificate if provided, otherwise
510 .It Ev TLS_CLIENT_HASH
511 The hash of the client certificate if provided, otherwise unset.
515 The TLS version negotiated with the peer.
517 The cipher suite negotiated with the peer.
518 .It Ev TLS_CIPHER_STRENGTH
519 The strength in bits for the symmetric cipher that is being used with
521 .It Ev TLS_CLIENT_NOT_AFTER
522 The time corresponding to the end of the validity period of the peer
523 certificate in the ISO 8601 format
524 .Pq e.g. Dq 2021-02-07T20:17:41Z .
525 .It Ev TLS_CLIENT_NOT_BEFORE
526 The time corresponding to the start of the validity period of the peer
527 certificate in the ISO 8601 format.
531 optionally supports FastCGI.
534 rule must be present in a server or location block.
535 Then, all requests matching that server or location will be handled
536 via the specified FastCGI backend.
538 By default the following variables
540 are sent, and carry the same semantics as with CGI.
541 More parameters can be added with the
579 TLS_CLIENT_NOT_BEFORE
584 To auto-detect the MIME type of the response
586 looks at the file extension and consults its internal table.
587 By default the following mappings are loaded, but they can be
588 overridden or extended using the
590 configuration option.
591 If no MIME is found, the value of
595 will be used, which is
596 .Dq application/octet-stream
599 .Bl -tag -offset indent -width 14m -compact
626 Messages and requests are logged by
630 facility or printed on
633 Requests are logged with the
636 Each request log entry has the following fields, separated by
641 Client IP address and the source port number, separated by a colon
653 Serve the current directory
654 .Bd -literal -offset indent
658 To serve the directory
660 and enable CGI scripts inside
662 .Bd -literal -offset indent
664 $ cat <<EOF > docs/cgi/hello
666 printf "20 text/plain\er\en"
669 $ chmod +x docs/cgi/hello
670 $ gmid -x '/cgi/*' docs
673 An X.509 certificate must be provided to run
675 using a configuration file.
676 First, the RSA certificate is created using a wildcard common name:
677 .Bd -literal -offset indent
678 # openssl genrsa \-out /etc/ssl/private/example.com.key 4096
679 # openssl req \-new \-x509 \e
680 \-key /etc/ssl/private/example.com.key \e
681 \-out /etc/ssl/example.com.crt \e
682 \-days 36500 \-nodes \e
683 \-subj "/CN=example.com"
684 # chmod 600 /etc/ssl/example.com.crt
685 # chmod 600 /etc/ssl/private/example.com.key
688 In the example above, a certificate is valid for one hundred years from
689 the date it was created, which is normal for TOFU.
691 The following is an example of a possible configuration for a site
692 that enables only TLSv1.3, adds a mime type for the file extension
694 and defines two virtual host:
695 .Bd -literal -offset indent
696 ipv6 on # enable ipv6
700 map "application/rtf" to-ext "rtf"
702 server "example.com" {
703 cert "/etc/ssl/example.com.crt"
704 key "/etc/ssl/private/example.com.key"
705 root "/var/gemini/example.com"
708 server "it.example.com" {
709 cert "/etc/ssl/example.com.crt"
710 key "/etc/ssl/private/example.com.key"
711 root "/var/gemini/it.example.com"
713 # enable cgi scripts inside "cgi-bin"
716 # set the language for text/gemini files
721 Yet another example, showing how to enable a
726 .Bd -literal -offset indent
730 server "example.com" {
731 cert "/path/to/cert.pem" # absolute path
732 key "/path/to/key.pem" # also absolute
733 root "/example.com" # relative to the chroot
735 location "/static/*" {
736 # load the following rules only for
737 # requests that matches "/static/*"
747 .Dq Flexible and Economical
748 UTF-8 decoder written by
749 .An Bjoern Hoehrmann .
754 program was written by
755 .An Omar Polo Aq Mt op@omarpolo.com .
759 All the root directories are opened during the daemon startup; if a
760 root directory is deleted and then re-created,
762 won't be able to serve files inside that directory until a restart.
763 This restriction only applies to the root directories and not their
766 a %2F sequence is indistinguishable from a literal slash: this is not
769 a %00 sequence is treated as invalid character and thus rejected.
