1 .\" Copyright (c) 2021, 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: February 26 2022$
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,
80 .Pq i.e. runs in the foreground to serve a directory from the shell
81 and looks for the following options
85 .It Fl d Ar certs-path
86 Directory where certificates for the config-less mode are stored.
88 .Pa $XDG_DATA_HOME/gmid ,
90 .Pa ~/.local/share/gmid .
97 Certificates for the given
99 are searched inside the
101 directory given with the
105 .Pa hostname.cert.pem
107 .Pa hostname.key.pem .
108 If a certificate or a key doesn't exist for a given hostname, they
109 will be generated automatically.
111 Print the usage and exit.
113 The port to listen on, by default 1965.
114 .It Fl V , Fl -version
115 Print the version and exit.
120 options increase the verbosity.
125 See the description of the
129 section below to learn how
132 Cannot be provided more than once.
134 The root directory to serve.
135 By default the current working directory is assumed.
137 .Sh CONFIGURATION FILE
138 The configuration file is divided into three sections:
141 User-defined variables may be defined and used later, simplifying the
143 .It Sy Global Options
147 Virtual hosts definition.
149 Media types and extensions.
152 Within the sections, empty lines are ignored and comments can be put
153 anywhere in the file using a hash mark
155 and extend to the end of the current line.
156 A boolean is either the symbol
160 A string is a sequence of characters wrapped in double quotes,
162 Multiple strings one next to the other are joined into a single
164 .Bd -literal -offset indent
165 # equivalent to "temporary-failure"
166 block return 40 "temporary" "-" "failure"
169 Furthermore, quoting is necessary only when a string needs to contain
171 .Pq like spaces or punctuation ,
172 something that looks like a number or a reserved keyword.
173 The last example could have been written also as:
174 .Bd -literal -offset indent
175 block return 40 temporary "-" failure
178 Strict ordering of the sections is not enforced, so that is possible
179 to mix macros, options and
182 However, defining all the
184 blocks after the macros and the global options is recommended.
186 Newlines are often optional, except around top-level instructions, and
189 can also be optionally used to separate options.
191 Additional configuration files can be included with the
193 keyword, for example:
194 .Bd -literal -offset indent
195 include "/etc/gmid.conf.local"
198 Macros can be defined that will later be expanded in context.
199 Macro names must start with a letter, digit or underscore and may
200 contain any of those characters.
201 Macros names may not be reserved words.
202 Macros are not expanded inside quotes.
204 Two kinds of macros are supported: variable-like and proper macros.
205 When a macro is invoked with a
207 before its name its expanded as a string, whereas when it's invoked
210 its expanded in-place.
213 .Bd -literal -offset indent
215 certdir = "/etc/keys"
216 common = "lang it; auto index on"
219 root $dir "/foo" # -> /var/gemini/foo
220 cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
221 key $certdir "/foo.pem" # -> /etc/keys/foo.pem
227 .It Ic chroot Ar path
229 the process to the given
231 The daemon has to be run with root privileges and thus the option
233 needs to be provided, so privileges can be dropped.
236 will enter the chroot after loading the TLS keys, but before opening
237 the virtual host root directories.
238 It's recommended to keep the TLS keys outside the chroot.
243 Enable or disable IPv6 support, off by default.
244 .It Ic port Ar portno
245 The port to listen on.
247 .It Ic prefork Ar number
248 Run the specified number of server processes.
249 This increases the performance and prevents delays when connecting to
251 When not in config-less mode,
253 runs 3 server processes by default.
254 The maximum number allowed is 16.
255 .It Ic protocols Ar string
256 Specify the TLS protocols to enable.
258 .Xr tls_config_parse_protocols 3
259 for the valid protocol string values.
260 By default, both TLSv1.3 and TLSv1.2 are enabled.
263 to enable only TLSv1.3.
264 .It Ic user Ar string
265 Run the daemon as the given user.
268 Every virtual host is defined by a
272 .It Ic server Ar hostname Brq ...
273 Match the server name using shell globbing rules.
274 It can be an explicit name,
275 .Ar www.example.com ,
276 or a name including a wildcards,
280 Followed by a block of options that is enclosed in curly brackets:
283 Specify an additional alias
286 .It Ic auto Ic index Ar bool
287 If no index file is found, automatically generate a directory listing.
289 .It Ic block Op Ic return Ar code Op Ar meta
290 Send a reply and close the connection;
297 .Dq temporary failure .
300 is in the 3x range, then
305 the following special sequences are supported:
306 .Bl -tag -width Ds -compact
308 is replaced with a single
311 is replaced with the request path.
313 is replaced with the query string of the request.
315 is replaced with the server port.
317 is replaced with the server name.
320 Path to the certificate to use for this server.
322 should contain a PEM encoded certificate.
323 This option is mandatory.
329 using shell globbing rules.
330 .It Ic default type Ar string
331 Set the default media type that is used if the media type for a
332 specified extension is not found.
333 If not specified, the
336 .Dq application/octet-stream .
337 .It Ic entrypoint Ar path
338 Handle all the requests for the current virtual host using the
342 relative to the current document root.
343 .It Ic env Ar name Cm = Ar value
344 Set the environment variable
348 when executing CGI scripts.
349 Can be provided more than once.
350 .\" don't document the "spawn <prog>" form because it probably won't
352 .It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
355 instead of serving files.
358 can either be a UNIX-domain socket or a TCP socket.
359 If the FastCGI application is listening on a UNIX domain socket,
361 is a local path name within the
367 keyword must be provided and
369 is interpreted as a hostname or an IP address.
371 can be either a port number or the name of a service enclosed in
373 If not specified defaults to 9000.
374 .It Ic index Ar string
375 Set the directory index file.
376 If not specified, it defaults to
379 Specify the private key to use for this server.
381 should contain a PEM encoded private key.
382 This option is mandatory.
383 .It Ic lang Ar string
384 Specify the language tag for the text/gemini content served.
387 parameter will be added in the response.
388 .It Ic location Ar path Brq ...
389 Specify server configuration rules for a specific location.
391 argument will be matched against the request path with shell globbing
393 In case of multiple location statements in the same context, the first
394 matching location will be put into effect and the later ones ignored.
395 Therefore is advisable to match for more specific paths first and for
396 generic ones later on.
399 section may include most of the server configuration rules
401 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
402 .Ic location , Ic param No and Ic proxy .
404 Enable or disable the logging for the current server or location block.
405 .It Ic param Ar name Cm = Ar value
412 Specify an OCSP response to be stapled during TLS handshakes
416 should contain a DER-format OCSP response retrieved from an
420 If the OCSP response in
422 is empty, OCSP stapling will not be used.
423 The default is to not use OCSP stapling.
424 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
425 Set up a reverse proxy.
426 The optional matching rules
430 can be used to enable proxying only for protocols matching
435 and/or whose request IRI matches
439 .Pq 1965 by default .
440 Matching happens using shell globbing rules.
442 In case of multiple matching proxy blocks in the same context, the
443 first matching proxy will be put into effect and the later ones
449 Specify the client certificate to use when making requests.
451 Specify the client certificate key to use when making requests.
452 .It Ic protocols Ar string
453 Specify the TLS protocols allowed when making remote requests.
455 .Xr tls_config_parse_protocols 3
456 function for the valid protocol string values.
457 By default, both TLSv1.2 and TLSv1.3 are enabled.
458 .It Ic relay-to Ar host : Ns Op Ar port
459 Relay the request to the given
464 This is the only mandatory option in a
467 .It Ic require Ic client Ic ca Ar file
468 Allow the proxying only from clients that provide a certificate
469 signed by the CA certificate in
471 .It Ic sni Ar hostname
474 instead of the one extracted from the
476 rule for the TLS handshake with the proxied gemini server.
477 .It Ic use-tls Ar bool
478 Specify whether to use TLS when connecting to the proxied host.
480 .It Ic verifyname Ar bool
481 Enable or disable the TLS server name verification.
484 .It Ic root Ar directory
485 Specify the root directory for this server
486 .Pq alas the current Dq document root .
487 It's relative to the chroot if enabled.
488 .It Ic require Ic client Ic ca Ar path
489 Allow requests only from clients that provide a certificate signed by
490 the CA certificate in
492 It needs to be a PEM-encoded certificate and it's not relative to the
494 .It Ic strip Ar number
497 components from the beginning of the path before doing a lookup in the
499 It's also considered for the
501 parameter in the scope of a
507 section must include one or more lines of the following syntax, enclosed
510 .It Ar type/subtype Ar name Op Ar name ...
515 to the specified extension
517 One or more names can be specified per line.
518 Earch line may end with an optional semicolon.
519 .It Ic include Ar file
520 Include types definition from an external file, for example
521 .Pa /usr/share/misc/mime.types .
524 When a request for an executable file matches the
526 rule, that file will be executed and its output fed to the client.
528 The CGI scripts are executed in the directory they reside and inherit
531 with these additional variables set:
533 .It Ev GATEWAY_INTERFACE
535 .It Ev GEMINI_DOCUMENT_ROOT
536 The root directory of the virtual host.
537 .It Ev GEMINI_SCRIPT_FILENAME
538 Full path to the CGI script being executed.
540 The full IRI of the request.
541 .It Ev GEMINI_URL_PATH
542 The path of the request.
544 The portion of the requested path that is derived from the the IRI
545 path hierarchy following the part that identifies the script itself.
547 .It Ev PATH_TRANSLATED
548 Present if and only if
551 It represent the translation of the
554 builds this by appending the
556 to the virtual host directory root.
558 The decoded query string.
559 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
560 Textual representation of the client IP.
561 .It Ev REQUEST_METHOD
562 This is present only for RFC3875 (CGI) compliance.
563 It's always set to the empty string.
567 that identifies the current CGI script.
569 The name of the server
571 The port the server is listening on.
572 .It Ev SERVER_PROTOCOL
574 .It Ev SERVER_SOFTWARE
575 The name and version of the server, i.e.
578 The string "Certificate" if the client used a certificate, otherwise
581 The subject of the client certificate if provided, otherwise unset.
582 .It Ev TLS_CLIENT_ISSUER
583 The is the issuer of the client certificate if provided, otherwise
585 .It Ev TLS_CLIENT_HASH
586 The hash of the client certificate if provided, otherwise unset.
590 The TLS version negotiated with the peer.
592 The cipher suite negotiated with the peer.
593 .It Ev TLS_CIPHER_STRENGTH
594 The strength in bits for the symmetric cipher that is being used with
596 .It Ev TLS_CLIENT_NOT_AFTER
597 The time corresponding to the end of the validity period of the peer
598 certificate in the ISO 8601 format
599 .Pq e.g. Dq 2021-02-07T20:17:41Z .
600 .It Ev TLS_CLIENT_NOT_BEFORE
601 The time corresponding to the start of the validity period of the peer
602 certificate in the ISO 8601 format.
606 optionally supports FastCGI.
609 rule must be present in a server or location block.
610 Then, all requests matching that server or location will be handled
611 via the specified FastCGI backend.
613 By default the following variables
615 are sent, and carry the same semantics as with CGI.
616 More parameters can be added with the
654 TLS_CLIENT_NOT_BEFORE
659 To auto-detect the MIME type of the response
661 looks at the file extension and consults an internal table.
662 If no MIME is found, the value of
667 .Dq application/octet-stream .
669 By default the following mappings are loaded, but they can be
670 overridden or extended using the
674 .Bl -tag -offset indent -width 14m -compact
701 Messages and requests are logged by
705 facility or printed on
708 Requests are logged with the
711 Each request log entry has the following fields, separated by
716 Client IP address and the source port number, separated by a colon
728 Serve the current directory
729 .Bd -literal -offset indent
733 To serve the directory
735 and enable CGI scripts inside
737 .Bd -literal -offset indent
739 $ cat <<EOF > docs/cgi/hello
741 printf "20 text/plain\er\en"
744 $ chmod +x docs/cgi/hello
745 $ gmid -x '/cgi/*' docs
748 An X.509 certificate must be provided to run
750 using a configuration file.
751 First, the RSA certificate is created using a wildcard common name:
752 .Bd -literal -offset indent
753 # openssl genrsa \-out /etc/ssl/private/example.com.key 4096
754 # openssl req \-new \-x509 \e
755 \-key /etc/ssl/private/example.com.key \e
756 \-out /etc/ssl/example.com.crt \e
757 \-days 36500 \-nodes \e
758 \-subj "/CN=example.com"
759 # chmod 600 /etc/ssl/example.com.crt
760 # chmod 600 /etc/ssl/private/example.com.key
763 In the example above, a certificate is valid for one hundred years from
764 the date it was created, which is normal for TOFU.
766 The following is an example of a possible configuration for a site
767 that enables only TLSv1.3, adds the MIME types mapping from
768 .Pa /usr/share/misc/mime.types
769 and defines two virtual host:
770 .Bd -literal -offset indent
771 ipv6 on # enable ipv6
776 include "/usr/share/misc/mime.types"
779 server "example.com" {
780 cert "/etc/ssl/example.com.crt"
781 key "/etc/ssl/private/example.com.key"
782 root "/var/gemini/example.com"
785 server "it.example.com" {
786 cert "/etc/ssl/example.com.crt"
787 key "/etc/ssl/private/example.com.key"
788 root "/var/gemini/it.example.com"
790 # enable cgi scripts inside "cgi-bin"
793 # set the language for text/gemini files
798 Yet another example, showing how to enable a
803 .Bd -literal -offset indent
807 server "example.com" {
808 cert "/path/to/cert.pem" # absolute path
809 key "/path/to/key.pem" # also absolute
810 root "/example.com" # relative to the chroot
812 location "/static/*" {
813 # load the following rules only for
814 # requests that matches "/static/*"
824 .Dq Flexible and Economical
825 UTF-8 decoder written by
826 .An Bjoern Hoehrmann .
831 program was written by
832 .An Omar Polo Aq Mt op@omarpolo.com .
836 All the root directories are opened during the daemon startup; if a
837 root directory is deleted and then re-created,
839 won't be able to serve files inside that directory until a restart.
840 This restriction only applies to the root directories and not their
843 a %2F sequence is indistinguishable from a literal slash: this is not
846 a %00 sequence is treated as invalid character and thus rejected.
