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: January 30 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 map Ar mime-type Cm to-ext Ar file-extension
249 Both argument are strings.
250 .It Ic port Ar portno
251 The port to listen on.
253 .It Ic prefork Ar number
254 Run the specified number of server processes.
255 This increases the performance and prevents delays when connecting to
257 When not in config-less mode,
259 runs 3 server processes by default.
260 The maximum number allowed is 16.
261 .It Ic protocols Ar string
262 Specify the TLS protocols to enable.
264 .Xr tls_config_parse_protocols 3
265 for the valid protocol string values.
266 By default, both TLSv1.3 and TLSv1.2 are enabled.
269 to enable only TLSv1.3.
270 .It Ic user Ar string
271 Run the daemon as the given user.
274 Every virtual host is defined by a
278 .It Ic server Ar hostname Brq ...
279 Match the server name using shell globbing rules.
280 It can be an explicit name,
281 .Ar www.example.com ,
282 or a name including a wildcards,
286 Followed by a block of options that is enclosed in curly brackets:
289 Specify an additional alias
292 .It Ic auto Ic index Ar bool
293 If no index file is found, automatically generate a directory listing.
295 .It Ic block Op Ic return Ar code Op Ar meta
296 Send a reply and close the connection;
303 .Dq temporary failure .
306 is in the 3x range, then
311 the following special sequences are supported:
312 .Bl -tag -width Ds -compact
314 is replaced with a single
317 is replaced with the request path.
319 is replaced with the query string of the request.
321 is replaced with the server port.
323 is replaced with the server name.
326 Path to the certificate to use for this server.
328 should contain a PEM encoded certificate.
329 This option is mandatory.
335 using shell globbing rules.
336 .It Ic default type Ar string
337 Set the default media type that is used if the media type for a
338 specified extension is not found.
339 If not specified, the
342 .Dq application/octet-stream .
343 .It Ic entrypoint Ar path
344 Handle all the requests for the current virtual host using the
348 relative to the current document root.
349 .It Ic env Ar name Cm = Ar value
350 Set the environment variable
354 when executing CGI scripts.
355 Can be provided more than once.
356 .\" don't document the "spawn <prog>" form because it probably won't
358 .It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
361 instead of serving files.
364 can either be a UNIX-domain socket or a TCP socket.
365 If the FastCGI application is listening on a UNIX domain socket,
367 is a local path name within the
373 keyword must be provided and
375 is interpreted as a hostname or an IP address.
377 can be either a port number or the name of a service enclosed in
379 If not specified defaults to 9000.
380 .It Ic index Ar string
381 Set the directory index file.
382 If not specified, it defaults to
385 Specify the private key to use for this server.
387 should contain a PEM encoded private key.
388 This option is mandatory.
389 .It Ic lang Ar string
390 Specify the language tag for the text/gemini content served.
393 parameter will be added in the response.
394 .It Ic location Ar path Brq ...
395 Specify server configuration rules for a specific location.
397 argument will be matched against the request path with shell globbing
399 In case of multiple location statements in the same context, the first
400 matching location will be put into effect and the later ones ignored.
401 Therefore is advisable to match for more specific paths first and for
402 generic ones later on.
405 section may include most of the server configuration rules
407 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
408 .Ic location , Ic param No and Ic proxy .
410 Enable or disable the logging for the current server or location block.
411 .It Ic param Ar name Cm = Ar value
418 Specify an OCSP response to be stapled during TLS handshakes
422 should contain a DER-format OCSP response retrieved from an
426 If the OCSP response in
428 is empty, OCSP stapling will not be used.
429 The default is to not use OCSP stapling.
430 .It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
431 Set up a reverse proxy.
432 The optional matching rules
436 can be used to enable proxying only for protocols matching
441 and/or whose request IRI matches
445 .Pq 1965 by default .
446 Matching happens using shell globbing rules.
448 In case of multiple matching proxy blocks in the same context, the
449 first matching proxy will be put into effect and the later ones
455 Specify the client certificate to use when making requests.
457 Specify the client certificate key to use when making requests.
458 .It Ic protocols Ar string
459 Specify the TLS protocols allowed when making remote requests.
461 .Xr tls_config_parse_protocols 3
462 function for the valid protocol string values.
463 By default, both TLSv1.2 and TLSv1.3 are enabled.
464 .It Ic relay-to Ar host : Ns Op Ar port
465 Relay the request to the given
470 This is the only mandatory option in a
473 .It Ic require Ic client Ic ca Ar file
474 Allow the proxying only from clients that provide a certificate
475 signed by the CA certificate in
477 .It Ic sni Ar hostname
480 instead of the one extracted from the
482 rule for the TLS handshake with the proxied gemini server.
483 .It Ic use-tls Ar bool
484 Specify whether to use TLS when connecting to the proxied host.
486 .It Ic verifyname Ar bool
487 Enable or disable the TLS server name verification.
490 .It Ic root Ar directory
491 Specify the root directory for this server
492 .Pq alas the current Dq document root .
493 It's relative to the chroot if enabled.
494 .It Ic require Ic client Ic ca Ar path
495 Allow requests only from clients that provide a certificate signed by
496 the CA certificate in
498 It needs to be a PEM-encoded certificate and it's not relative to the
500 .It Ic strip Ar number
503 components from the beginning of the path before doing a lookup in the
505 It's also considered for the
507 parameter in the scope of a
513 section must include one or more lines of the following syntax, enclosed
516 .It Ar type/subtype Ar name Op Ar name ...
521 to the specified extension
523 One or more names can be specified per line.
524 Earch line may end with an optional semicolon.
525 .It Ic include Ar file
526 Include types definition from an external file, for example
527 .Pa /usr/share/misc/mime.types .
530 When a request for an executable file matches the
532 rule, that file will be executed and its output fed to the client.
534 The CGI scripts are executed in the directory they reside and inherit
537 with these additional variables set:
539 .It Ev GATEWAY_INTERFACE
541 .It Ev GEMINI_DOCUMENT_ROOT
542 The root directory of the virtual host.
543 .It Ev GEMINI_SCRIPT_FILENAME
544 Full path to the CGI script being executed.
546 The full IRI of the request.
547 .It Ev GEMINI_URL_PATH
548 The path of the request.
550 The portion of the requested path that is derived from the the IRI
551 path hierarchy following the part that identifies the script itself.
553 .It Ev PATH_TRANSLATED
554 Present if and only if
557 It represent the translation of the
560 builds this by appending the
562 to the virtual host directory root.
564 The decoded query string.
565 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
566 Textual representation of the client IP.
567 .It Ev REQUEST_METHOD
568 This is present only for RFC3875 (CGI) compliance.
569 It's always set to the empty string.
573 that identifies the current CGI script.
575 The name of the server
577 The port the server is listening on.
578 .It Ev SERVER_PROTOCOL
580 .It Ev SERVER_SOFTWARE
581 The name and version of the server, i.e.
584 The string "Certificate" if the client used a certificate, otherwise
587 The subject of the client certificate if provided, otherwise unset.
588 .It Ev TLS_CLIENT_ISSUER
589 The is the issuer of the client certificate if provided, otherwise
591 .It Ev TLS_CLIENT_HASH
592 The hash of the client certificate if provided, otherwise unset.
596 The TLS version negotiated with the peer.
598 The cipher suite negotiated with the peer.
599 .It Ev TLS_CIPHER_STRENGTH
600 The strength in bits for the symmetric cipher that is being used with
602 .It Ev TLS_CLIENT_NOT_AFTER
603 The time corresponding to the end of the validity period of the peer
604 certificate in the ISO 8601 format
605 .Pq e.g. Dq 2021-02-07T20:17:41Z .
606 .It Ev TLS_CLIENT_NOT_BEFORE
607 The time corresponding to the start of the validity period of the peer
608 certificate in the ISO 8601 format.
612 optionally supports FastCGI.
615 rule must be present in a server or location block.
616 Then, all requests matching that server or location will be handled
617 via the specified FastCGI backend.
619 By default the following variables
621 are sent, and carry the same semantics as with CGI.
622 More parameters can be added with the
660 TLS_CLIENT_NOT_BEFORE
665 To auto-detect the MIME type of the response
667 looks at the file extension and consults an internal table.
668 If no MIME is found, the value of
673 .Dq application/octet-stream .
675 By default the following mappings are loaded, but they can be
676 overridden or extended using the
682 .Bl -tag -offset indent -width 14m -compact
709 Messages and requests are logged by
713 facility or printed on
716 Requests are logged with the
719 Each request log entry has the following fields, separated by
724 Client IP address and the source port number, separated by a colon
736 Serve the current directory
737 .Bd -literal -offset indent
741 To serve the directory
743 and enable CGI scripts inside
745 .Bd -literal -offset indent
747 $ cat <<EOF > docs/cgi/hello
749 printf "20 text/plain\er\en"
752 $ chmod +x docs/cgi/hello
753 $ gmid -x '/cgi/*' docs
756 An X.509 certificate must be provided to run
758 using a configuration file.
759 First, the RSA certificate is created using a wildcard common name:
760 .Bd -literal -offset indent
761 # openssl genrsa \-out /etc/ssl/private/example.com.key 4096
762 # openssl req \-new \-x509 \e
763 \-key /etc/ssl/private/example.com.key \e
764 \-out /etc/ssl/example.com.crt \e
765 \-days 36500 \-nodes \e
766 \-subj "/CN=example.com"
767 # chmod 600 /etc/ssl/example.com.crt
768 # chmod 600 /etc/ssl/private/example.com.key
771 In the example above, a certificate is valid for one hundred years from
772 the date it was created, which is normal for TOFU.
774 The following is an example of a possible configuration for a site
775 that enables only TLSv1.3, adds a mime type for the file extension
777 and defines two virtual host:
778 .Bd -literal -offset indent
779 ipv6 on # enable ipv6
783 map "application/rtf" to-ext "rtf"
785 server "example.com" {
786 cert "/etc/ssl/example.com.crt"
787 key "/etc/ssl/private/example.com.key"
788 root "/var/gemini/example.com"
791 server "it.example.com" {
792 cert "/etc/ssl/example.com.crt"
793 key "/etc/ssl/private/example.com.key"
794 root "/var/gemini/it.example.com"
796 # enable cgi scripts inside "cgi-bin"
799 # set the language for text/gemini files
804 Yet another example, showing how to enable a
809 .Bd -literal -offset indent
813 server "example.com" {
814 cert "/path/to/cert.pem" # absolute path
815 key "/path/to/key.pem" # also absolute
816 root "/example.com" # relative to the chroot
818 location "/static/*" {
819 # load the following rules only for
820 # requests that matches "/static/*"
830 .Dq Flexible and Economical
831 UTF-8 decoder written by
832 .An Bjoern Hoehrmann .
837 program was written by
838 .An Omar Polo Aq Mt op@omarpolo.com .
842 All the root directories are opened during the daemon startup; if a
843 root directory is deleted and then re-created,
845 won't be able to serve files inside that directory until a restart.
846 This restriction only applies to the root directories and not their
849 a %2F sequence is indistinguishable from a literal slash: this is not
852 a %00 sequence is treated as invalid character and thus rejected.
