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.
66 Write the daemon pid to the given location.
68 will also act as lock: if another process is holding a lock on that
74 If no configuration file is given,
76 will look for the following options
80 .It Fl d Pa certs-path
81 Directory where certificates for the config-less mode are stored.
83 .Pa $XDG_DATA_HOME/gmid ,
85 .Pa ~/.local/share/gmid .
90 Certificates for the given
92 are searched inside the
94 directory given with the
100 .Pa hostname.key.pem .
101 If a certificate or key don't exists for a given hostname they
102 will be automatically generated.
104 Print the usage and exit.
106 The port to listen on, by default 1965.
107 .It Fl V , Fl -version
108 Print the version and exit.
113 options increase the verbosity.
115 Enable execution of CGI scripts.
116 See the description of the
118 option in the section
123 Cannot be provided more than once.
125 The root directory to serve.
126 By default the current working directory is assumed.
128 .Sh CONFIGURATION FILE
129 The configuration file is divided into three sections:
132 User-defined variables may be defined and used later, simplifying the
134 .It Sy Global Options
138 Virtual hosts definition.
141 Within the sections, empty lines are ignored and comments can be put
142 anywhere in the file using a hash mark
144 and extend to the end of the current line.
145 A boolean is either the symbol
149 A string is a sequence of characters wrapped in double quotes,
151 Multiple strings one next to the other are joined into a single
153 .Bd -literal -offset indent
154 # equivalent to "temporary-failure"
155 block return 40 "temporary" "-" "failure"
158 Furthermore, quoting is necessary only when a string needs to contain
159 spaces, something that looks like a number or a reserved keyword.
160 The last example could have been written also as:
161 .Bd -literal -offset indent
162 block return 40 temporary "-" failure
165 Strict ordering of the sections is not enforced, so that is possible
166 to mix macros, options and
169 However, defining all the
171 blocks after the macros and the global options is recommended.
173 Macros can be defined that will later be expanded in context.
174 Macro names must start with a letter, digit or underscore and may
175 contain any of those characters.
176 Macros names may not be reserved words.
177 Macros are not expanded inside quotes.
180 .Bd -literal -offset indent
185 root $dir "/foo" # -> /var/gemini/foo
186 cert $cert "/foo.crt" # -> /etc/keys/foo.crt
187 key $cert "/foo.pem" # -> /etc/keys/foo.pem
192 .It Ic chroot Pa path
194 the process to the given
196 The daemon has to be run with root privileges and thus the option
198 needs to be provided, so privileges can be dropped.
201 will enter the chroot after loading the TLS keys, but before opening
202 the virtual host root directories.
203 It's recommended to keep the TLS keys outside the chroot.
208 Enable or disable IPv6 support, off by default.
209 .It Ic map Ar mime-type Cm to-ext Ar file-extension
214 Both argument are strings.
215 .It Ic port Ar portno
216 The port to listen on.
218 .It Ic prefork Ar number
219 Run the specified number of server processes.
220 This increases the performance and prevents delays when connecting to
222 When not in config-less mode,
224 runs 3 server processes by default.
225 The maximum number allowed is 16.
226 .It Ic protocols Ar string
227 Specify the TLS protocols to enable.
229 .Xr tls_config_parse_protocols 3
230 for the valid protocol string values.
231 By default, both TLSv1.3 and TLSv1.2 are enabled.
234 to enable only TLSv1.3.
235 .It Ic user Ar string
236 Run the daemon as the given user.
239 Every virtual host is defined by a
243 .It Ic server Ar hostname Brq ...
244 Match the server name using shell globbing rules.
245 It can be an explicit name,
246 .Ar www.example.com ,
247 or a name including a wildcards,
251 Followed by a block of options that is enclosed in curly brackets:
254 Specify an additional alias
257 .It Ic auto Ic index Ar bool
258 If no index file is found, automatically generate a directory listing.
260 .It Ic block Op Ic return Ar code Op Ar meta
261 Send a reply and close the connection;
268 .Dq temporary failure .
271 is in the 3x range, then
276 the following special sequences are supported:
277 .Bl -tag -width Ds -compact
279 is replaced with a single
282 is replaced with the request path.
284 is replaced with the query string of the request.
286 is replaced with the server port.
288 is replaced with the server name.
291 Path to the certificate to use for this server.
294 should contain a PEM encoded certificate.
295 This option is mandatory.
297 Execute CGI scripts that matches
299 using shell globbing rules.
300 .It Ic default type Ar string
301 Set the default media type that is used if the media type for a
302 specified extension is not found.
303 If not specified, the
306 .Dq application/octet-stream .
307 .It Ic entrypoint Pa path
308 Handle all the requests for the current virtual host using the
311 relative to the current document root.
312 .It Ic env Ar name Cm = Ar value
313 Set the environment variable
317 when executing CGI scripts.
318 Can be provided more than once.
319 .\" don't document the "spawn <prog>" form because it probably won't
321 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
322 Enable FastCGI instead of serving files.
325 can either be a UNIX-domain socket or a TCP socket.
326 If the FastCGI application is listening on a UNIX domain socket,
328 is a local path name within the
334 keyword must be provided and
336 is interpreted as a hostname or an IP address.
338 can be either a port number or the name of a service enclosed in
340 If not specified defaults to 9000.
341 .It Ic index Ar string
342 Set the directory index file.
343 If not specified, it defaults to
346 Specify the private key to use for this server.
349 should contain a PEM encoded private key.
350 This option is mandatory.
351 .It Ic lang Ar string
352 Specify the language tag for the text/gemini content served.
355 parameter will be added in the response.
356 .It Ic location Pa path Brq ...
357 Specify server configuration rules for a specific location.
360 argument will be matched against the request path with shell globbing
362 In case of multiple location statements in the same context, the first
363 matching location will be put into effect and the later ones ignored.
364 Therefore is advisable to match for more specific paths first and for
365 generic ones later on.
368 section may include most of the server configuration rules
370 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
371 .Ic location No and Ic param .
373 Enable or disable the logging for the current server or location block.
374 .It Ic param Ar name Cm = Ar value
380 .It Ic root Pa directory
381 Specify the root directory for this server
382 .Pq alas the current Dq document root .
383 It's relative to the chroot if enabled.
384 .It Ic require Ic client Ic ca Pa path
385 Allow requests only from clients that provide a certificate signed by
386 the CA certificate in
388 It needs to be a PEM-encoded certificate and it's not relative to the
390 .It Ic strip Ar number
393 components from the beginning of the path before doing a lookup in the
395 It's also considered for the
397 parameter in the scope of a
401 When a request for an executable file matches the
403 rule, that file will be execute and its output fed to the client.
405 The CGI scripts are executed in the directory they reside and inherit
408 with these additional variables set:
410 .It Ev GATEWAY_INTERFACE
412 .It Ev GEMINI_DOCUMENT_ROOT
413 The root directory of the virtual host.
414 .It Ev GEMINI_SCRIPT_FILENAME
415 Full path to the CGI script being executed.
417 The full IRI of the request.
418 .It Ev GEMINI_URL_PATH
419 The path of the request.
421 The portion of the requested path that is derived from the the IRI
422 path hierarchy following the part that identifies the script itself.
424 .It Ev PATH_TRANSLATED
425 Present if and only if
428 It represent the translation of the
431 builds this by appending the
433 to the virtual host directory root.
435 The decoded query string.
436 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
437 Textual representation of the client IP.
438 .It Ev REQUEST_METHOD
439 This is present only for RFC3875 (CGI) compliance.
440 It's always set to the empty string.
444 that identifies the current CGI script.
446 The name of the server
448 The port the server is listening on.
449 .It Ev SERVER_PROTOCOL
451 .It Ev SERVER_SOFTWARE
452 The name and version of the server, i.e.
455 The string "Certificate" if the client used a certificate, otherwise
458 The subject of the client certificate if provided, otherwise unset.
459 .It Ev TLS_CLIENT_ISSUER
460 The is the issuer of the client certificate if provided, otherwise
462 .It Ev TLS_CLIENT_HASH
463 The hash of the client certificate if provided, otherwise unset.
467 The TLS version negotiated with the peer.
469 The cipher suite negotiated with the peer.
470 .It Ev TLS_CIPHER_STRENGTH
471 The strength in bits for the symmetric cipher that is being used with
473 .It Ev TLS_CLIENT_NOT_AFTER
474 The time corresponding to the end of the validity period of the peer
475 certificate in the ISO 8601 format
476 .Pq e.g. Dq 2021-02-07T20:17:41Z .
477 .It Ev TLS_CLIENT_NOT_BEFORE
478 The time corresponding to the start of the validity period of the peer
479 certificate in the ISO 8601 format.
483 optionally supports FastCGI.
486 rule must be present in a server or location block.
487 Then, all requests matching that server or location will be handled
488 via the specified FastCGI backend.
490 By default the following variables
492 are sent, and carry the same semantics as with CGI.
493 More parameters can be added with the
531 TLS_CLIENT_NOT_BEFORE
536 To auto-detect the MIME type of the response
538 looks at the file extension and consults its internal table.
539 By default the following mappings are loaded, but they can be
540 overridden or extended using the
542 configuration option.
543 If no MIME is found, the value of
547 will be used, which is
548 .Dq application/octet-stream
551 .Bl -tag -offset indent -width 14m -compact
578 Serve the current directory
579 .Bd -literal -offset indent
583 To serve the directory
585 and enable CGI scripts inside
587 .Bd -literal -offset indent
589 $ cat <<EOF > docs/cgi/hello
591 printf "20 text/plain\\r\\n"
594 $ chmod +x docs/cgi/hello
595 $ gmid -x '/cgi/*' docs
598 The following is an example of a possible configuration for a site
599 that enables only TLSv1.3, adds a mime type for the file extension
600 "rtf" and defines two virtual host:
601 .Bd -literal -offset indent
602 ipv6 on # enable ipv6
606 map "application/rtf" to-ext "rtf"
608 server "example.com" {
609 cert "/path/to/cert.pem"
610 key "/path/to/key.pem"
611 root "/var/gemini/example.com"
614 server "it.example.com" {
615 cert "/path/to/cert.pem"
616 key "/path/to/key.pem"
617 root "/var/gemini/it.example.com"
619 # enable cgi scripts inside "cgi-bin"
622 # set the language for text/gemini files
627 Yet another example, showing how to enable a
632 .Bd -literal -offset indent
636 server "example.com" {
637 cert "/path/to/cert.pem" # absolute path
638 key "/path/to/key.pem" # also absolute
639 root "/example.com" # relative to the chroot
641 location "/static/*" {
642 # load the following rules only for
643 # requests that matches "/static/*"
653 .Dq Flexible and Economical
654 UTF-8 decoder written by
655 .An Bjoern Hoehrmann .
660 program was written by
661 .An Omar Polo Aq Mt op@omarpolo.com .
665 All the root directories are opened during the daemon startup; if a
666 root directory is deleted and then re-created,
668 won't be able to serve files inside that directory until a restart.
669 This restriction only applies to the root directories and not their
672 a %2F sequence is indistinguishable from a literal slash: this is not
675 a %00 sequence is treated as invalid character and thus rejected.
