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
160 .Pq like spaces or punctuation ,
161 something that looks like a number or a reserved keyword.
162 The last example could have been written also as:
163 .Bd -literal -offset indent
164 block return 40 temporary "-" failure
167 Strict ordering of the sections is not enforced, so that is possible
168 to mix macros, options and
171 However, defining all the
173 blocks after the macros and the global options is recommended.
175 Newlines are often optional, except around top-level instructions, and
178 can also be optionally used to separate options.
180 Additional configuration files can be included with the
182 keyword, for example:
183 .Bd -literal -offset indent
184 include "/etc/gmid.conf.local"
187 Macros can be defined that will later be expanded in context.
188 Macro names must start with a letter, digit or underscore and may
189 contain any of those characters.
190 Macros names may not be reserved words.
191 Macros are not expanded inside quotes.
193 Two kinds of macros are supported: variable-like and proper macros.
194 When a macro is invoked with a
196 before its name its expanded as a string, whereas when it's invoked
199 its expanded in-place.
202 .Bd -literal -offset indent
204 certdir = "/etc/keys"
205 common = "lang it; auto index on"
208 root $dir "/foo" # -> /var/gemini/foo
209 cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
210 key $certdir "/foo.pem" # -> /etc/keys/foo.pem
216 .It Ic chroot Pa path
218 the process to the given
220 The daemon has to be run with root privileges and thus the option
222 needs to be provided, so privileges can be dropped.
225 will enter the chroot after loading the TLS keys, but before opening
226 the virtual host root directories.
227 It's recommended to keep the TLS keys outside the chroot.
232 Enable or disable IPv6 support, off by default.
233 .It Ic map Ar mime-type Cm to-ext Ar file-extension
238 Both argument are strings.
239 .It Ic port Ar portno
240 The port to listen on.
242 .It Ic prefork Ar number
243 Run the specified number of server processes.
244 This increases the performance and prevents delays when connecting to
246 When not in config-less mode,
248 runs 3 server processes by default.
249 The maximum number allowed is 16.
250 .It Ic protocols Ar string
251 Specify the TLS protocols to enable.
253 .Xr tls_config_parse_protocols 3
254 for the valid protocol string values.
255 By default, both TLSv1.3 and TLSv1.2 are enabled.
258 to enable only TLSv1.3.
259 .It Ic user Ar string
260 Run the daemon as the given user.
263 Every virtual host is defined by a
267 .It Ic server Ar hostname Brq ...
268 Match the server name using shell globbing rules.
269 It can be an explicit name,
270 .Ar www.example.com ,
271 or a name including a wildcards,
275 Followed by a block of options that is enclosed in curly brackets:
278 Specify an additional alias
281 .It Ic auto Ic index Ar bool
282 If no index file is found, automatically generate a directory listing.
284 .It Ic block Op Ic return Ar code Op Ar meta
285 Send a reply and close the connection;
292 .Dq temporary failure .
295 is in the 3x range, then
300 the following special sequences are supported:
301 .Bl -tag -width Ds -compact
303 is replaced with a single
306 is replaced with the request path.
308 is replaced with the query string of the request.
310 is replaced with the server port.
312 is replaced with the server name.
315 Path to the certificate to use for this server.
318 should contain a PEM encoded certificate.
319 This option is mandatory.
321 Execute CGI scripts that matches
323 using shell globbing rules.
324 .It Ic default type Ar string
325 Set the default media type that is used if the media type for a
326 specified extension is not found.
327 If not specified, the
330 .Dq application/octet-stream .
331 .It Ic entrypoint Pa path
332 Handle all the requests for the current virtual host using the
335 relative to the current document root.
336 .It Ic env Ar name Cm = Ar value
337 Set the environment variable
341 when executing CGI scripts.
342 Can be provided more than once.
343 .\" don't document the "spawn <prog>" form because it probably won't
345 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
346 Enable FastCGI instead of serving files.
349 can either be a UNIX-domain socket or a TCP socket.
350 If the FastCGI application is listening on a UNIX domain socket,
352 is a local path name within the
358 keyword must be provided and
360 is interpreted as a hostname or an IP address.
362 can be either a port number or the name of a service enclosed in
364 If not specified defaults to 9000.
365 .It Ic index Ar string
366 Set the directory index file.
367 If not specified, it defaults to
370 Specify the private key to use for this server.
373 should contain a PEM encoded private key.
374 This option is mandatory.
375 .It Ic lang Ar string
376 Specify the language tag for the text/gemini content served.
379 parameter will be added in the response.
380 .It Ic location Pa path Brq ...
381 Specify server configuration rules for a specific location.
384 argument will be matched against the request path with shell globbing
386 In case of multiple location statements in the same context, the first
387 matching location will be put into effect and the later ones ignored.
388 Therefore is advisable to match for more specific paths first and for
389 generic ones later on.
392 section may include most of the server configuration rules
394 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
395 .Ic location No and Ic param .
397 Enable or disable the logging for the current server or location block.
398 .It Ic param Ar name Cm = Ar value
404 .It Ic root Pa directory
405 Specify the root directory for this server
406 .Pq alas the current Dq document root .
407 It's relative to the chroot if enabled.
408 .It Ic require Ic client Ic ca Pa path
409 Allow requests only from clients that provide a certificate signed by
410 the CA certificate in
412 It needs to be a PEM-encoded certificate and it's not relative to the
414 .It Ic strip Ar number
417 components from the beginning of the path before doing a lookup in the
419 It's also considered for the
421 parameter in the scope of a
425 When a request for an executable file matches the
427 rule, that file will be execute and its output fed to the client.
429 The CGI scripts are executed in the directory they reside and inherit
432 with these additional variables set:
434 .It Ev GATEWAY_INTERFACE
436 .It Ev GEMINI_DOCUMENT_ROOT
437 The root directory of the virtual host.
438 .It Ev GEMINI_SCRIPT_FILENAME
439 Full path to the CGI script being executed.
441 The full IRI of the request.
442 .It Ev GEMINI_URL_PATH
443 The path of the request.
445 The portion of the requested path that is derived from the the IRI
446 path hierarchy following the part that identifies the script itself.
448 .It Ev PATH_TRANSLATED
449 Present if and only if
452 It represent the translation of the
455 builds this by appending the
457 to the virtual host directory root.
459 The decoded query string.
460 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
461 Textual representation of the client IP.
462 .It Ev REQUEST_METHOD
463 This is present only for RFC3875 (CGI) compliance.
464 It's always set to the empty string.
468 that identifies the current CGI script.
470 The name of the server
472 The port the server is listening on.
473 .It Ev SERVER_PROTOCOL
475 .It Ev SERVER_SOFTWARE
476 The name and version of the server, i.e.
479 The string "Certificate" if the client used a certificate, otherwise
482 The subject of the client certificate if provided, otherwise unset.
483 .It Ev TLS_CLIENT_ISSUER
484 The is the issuer of the client certificate if provided, otherwise
486 .It Ev TLS_CLIENT_HASH
487 The hash of the client certificate if provided, otherwise unset.
491 The TLS version negotiated with the peer.
493 The cipher suite negotiated with the peer.
494 .It Ev TLS_CIPHER_STRENGTH
495 The strength in bits for the symmetric cipher that is being used with
497 .It Ev TLS_CLIENT_NOT_AFTER
498 The time corresponding to the end of the validity period of the peer
499 certificate in the ISO 8601 format
500 .Pq e.g. Dq 2021-02-07T20:17:41Z .
501 .It Ev TLS_CLIENT_NOT_BEFORE
502 The time corresponding to the start of the validity period of the peer
503 certificate in the ISO 8601 format.
507 optionally supports FastCGI.
510 rule must be present in a server or location block.
511 Then, all requests matching that server or location will be handled
512 via the specified FastCGI backend.
514 By default the following variables
516 are sent, and carry the same semantics as with CGI.
517 More parameters can be added with the
555 TLS_CLIENT_NOT_BEFORE
560 To auto-detect the MIME type of the response
562 looks at the file extension and consults its internal table.
563 By default the following mappings are loaded, but they can be
564 overridden or extended using the
566 configuration option.
567 If no MIME is found, the value of
571 will be used, which is
572 .Dq application/octet-stream
575 .Bl -tag -offset indent -width 14m -compact
602 Serve the current directory
603 .Bd -literal -offset indent
607 To serve the directory
609 and enable CGI scripts inside
611 .Bd -literal -offset indent
613 $ cat <<EOF > docs/cgi/hello
615 printf "20 text/plain\\r\\n"
618 $ chmod +x docs/cgi/hello
619 $ gmid -x '/cgi/*' docs
622 The following is an example of a possible configuration for a site
623 that enables only TLSv1.3, adds a mime type for the file extension
624 "rtf" and defines two virtual host:
625 .Bd -literal -offset indent
626 ipv6 on # enable ipv6
630 map "application/rtf" to-ext "rtf"
632 server "example.com" {
633 cert "/path/to/cert.pem"
634 key "/path/to/key.pem"
635 root "/var/gemini/example.com"
638 server "it.example.com" {
639 cert "/path/to/cert.pem"
640 key "/path/to/key.pem"
641 root "/var/gemini/it.example.com"
643 # enable cgi scripts inside "cgi-bin"
646 # set the language for text/gemini files
651 Yet another example, showing how to enable a
656 .Bd -literal -offset indent
660 server "example.com" {
661 cert "/path/to/cert.pem" # absolute path
662 key "/path/to/key.pem" # also absolute
663 root "/example.com" # relative to the chroot
665 location "/static/*" {
666 # load the following rules only for
667 # requests that matches "/static/*"
677 .Dq Flexible and Economical
678 UTF-8 decoder written by
679 .An Bjoern Hoehrmann .
684 program was written by
685 .An Omar Polo Aq Mt op@omarpolo.com .
689 All the root directories are opened during the daemon startup; if a
690 root directory is deleted and then re-created,
692 won't be able to serve files inside that directory until a restart.
693 This restriction only applies to the root directories and not their
696 a %2F sequence is indistinguishable from a literal slash: this is not
699 a %00 sequence is treated as invalid character and thus rejected.
