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
38 is a simple and minimal gemini server that can serve static files,
39 execute CGI scripts and talk to FastCGI applications.
40 It can run without a configuration file with a limited set of features
44 rereads the configuration file when it receives
47 The options are as follows:
50 Specify the configuration file.
52 Stays and logs on the foreground.
54 Check that the configuration is valid, but don't start the server.
58 pid to the given path.
61 If no configuration file is given,
63 will look for the following options
67 .It Fl d Pa certs-path
68 Directory where certificates for the config-less mode are stored.
70 .Pa $XDG_DATA_HOME/gmid ,
72 .Pa ~/.local/share/gmid .
74 The hostname, by default
76 Certificates for the given
78 are searched inside the
80 directory given with the
86 .Pa hostname.key.pem .
87 If a certificate or key don't exists for a given hostname they
88 will be automatically generated.
90 Print the usage and exit.
92 The port to listen on, by default 1965.
97 options increase the verbosity.
99 Enable execution of CGI scripts.
100 See the description of the
102 option in the section
107 Cannot be provided more than once.
109 The root directory to serve.
110 By default the current working directory is assumed.
112 .Sh CONFIGURATION FILE
113 The configuration file is divided into two sections:
115 .It Sy Global Options
119 Virtual hosts definition.
122 Within the sections, empty lines are ignored and comments can be put
123 anywhere in the file using a hash mark
125 and extend to the end of the current line.
126 A boolean is either the symbol
130 A string is a sequence of characters wrapped in double quotes,
134 .It Ic chroot Pa path
136 the process to the given
138 The daemon has to be run with root privileges and thus the option
140 needs to be provided, so privileges can be dropped.
143 will enter the chroot after loading the TLS keys, but before opening
144 the virtual host root directories.
145 It's recommended to keep the TLS keys outside the chroot.
150 Enable or disable IPv6 support.
152 .It Ic mime Ar mime-type Ar file-extension
153 Add a mapping for the given
157 Both argument are strings.
158 .It Ic port Ar portno
159 The port to listen on.
161 .It Ic prefork Ar number
162 Run the specified number of server processes.
163 This increases the performance and prevents delays when connecting to
166 runs 3 server processes by default, when not in config-less mode.
167 The maximum number allowed is 16.
168 .It Ic protocols Ar string
169 Specify the TLS protocols to enable.
171 .Xr tls_config_parse_protocols 3
172 for the valid protocol string values.
173 By default, both TLSv1.3 and TLSv1.2 are enabled.
176 to enable only TLSv1.3.
177 .It Ic user Ar string
178 Run the daemon as the given user.
181 Every virtual host is defined by a
185 .It Ic server Ar hostname Brq ...
186 Match the server name using shell globbing rules.
187 This can be an explicit name,
188 .Ar www.example.com ,
189 or a name including a wildcards,
193 Followed by a block of options that is enclosed in curly brackets:
196 Specify an additional alias
199 .It Ic auto Ic index Ar bool
200 If no index file is found, automatically generate a directory listing.
201 It's disabled by default.
202 .It Ic block Op Ic return Ar code Op Ar meta
203 Send a reply and close the connection;
209 .Dq temporary failure
213 is in the 3x range, then
218 the following special sequences are replaced:
221 is replaced with a single
224 is replaced with the request path.
226 is replaced with the query string of the request.
228 is replaced with the server port.
230 is replaced with the server name.
233 Path to the certificate to use for this server.
236 should contain a PEM encoded certificate.
237 This option is mandatory.
239 Execute CGI scripts that matches
241 using shell globbing rules.
242 .It Ic default type Ar string
243 Set the default media type that is used if the media type for a
244 specified extension is not found.
245 If not specified, the
248 .Dq application/octet-stream .
249 .It Ic entrypoint Pa path
250 Handle all the requests for the current virtual host using the
253 .It Ic env Ar name Ar value
254 Set the environment variable
258 when executing CGI scripts.
259 Can be provided more than once.
260 .\" don't document the "spawn <prog>" form because it probably won't
262 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Ar port Oc
263 Enable FastCGI instead of serving files.
266 can either be a UNIX domain socket or a TCP socket.
267 If the FastCGI application is listening on a UNIX domain socket,
269 is a local path name within the
275 keyword must be provided and
277 is interpreted as a hostname or an IP address.
279 can be either a port number or the name of a service enclosed in
281 If it's not specified defaults to 9000.
282 .It Ic index Ar string
283 Set the directory index file.
284 If not specified, it defaults to
287 Specify the private key to use for this server.
290 should contain a PEM encoded private key.
291 This option is mandatory.
292 .It Ic lang Ar string
293 Specify the language tag for the text/gemini content served.
296 parameter will be added in the response.
297 .It Ic location Pa path Brq ...
298 Specify server configuration rules for a specific location.
301 argument will be matched against the request path with shell globbing
303 In case of multiple location statements in the same context, the first
304 matching location will be put into effect and the later ones ignored.
305 Therefore is advisable to match for more specific paths first and for
306 generic ones later on.
309 section may include most of the server configuration rules
311 .Ic alias , Ic cert , Ic env , Ic key , Ic location ,
312 .Ic entrypoint No and Ic cgi .
313 .It Ic root Pa directory
314 Specify the root directory for this server.
315 It's relative to the chroot, if enabled.
316 .It Ic require Ic client Ic ca Pa path
317 Allow requests only from clients that provide a certificate signed by
318 the CA certificate in
320 It needs to be a PEM-encoded certificate and it's not relative to the
322 .It Ic strip Ar number
325 components from the beginning of the path before doing a lookup in the
327 It's also considered for the
329 parameter in the scope of a
333 When a request for an executable file matches the
335 rule, that file will be execute and its output fed to the client.
337 The CGI scripts are executed in the directory they reside and inherit
340 with these additional variables set:
342 .It Ev GATEWAY_INTERFACE
344 .It Ev GEMINI_DOCUMENT_ROOT
345 The root directory of the virtual host.
346 .It Ev GEMINI_SCRIPT_FILENAME
347 Full path to the CGI script being executed.
349 The full IRI of the request.
350 .It Ev GEMINI_URL_PATH
351 The path of the request.
353 The portion of the requested path that is derived from the the IRI
354 path hierarchy following the part that identifies the script itself.
356 .It Ev PATH_TRANSLATED
357 Present if and only if
360 It represent the translation of the
363 builds this by appending the
365 to the virtual host directory root.
367 The decoded query string.
368 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
369 Textual representation of the client IP.
370 .It Ev REQUEST_METHOD
371 This is present only for RFC3875 (CGI) compliance.
372 It's always set to the empty string.
376 that identifies the current CGI script.
378 The name of the server
380 The port the server is listening on.
381 .It Ev SERVER_PROTOCOL
383 .It Ev SERVER_SOFTWARE
384 The name and version of the server, i.e.
387 The string "Certificate" if the client used a certificate, otherwise
390 The subject of the client certificate if provided, otherwise unset.
391 .It Ev TLS_CLIENT_ISSUER
392 The is the issuer of the client certificate if provided, otherwise
394 .It Ev TLS_CLIENT_HASH
395 The hash of the client certificate if provided, otherwise unset.
399 The TLS version negotiated with the peer.
401 The cipher suite negotiated with the peer.
402 .It Ev TLS_CIPHER_STRENGTH
403 The strength in bits for the symmetric cipher that is being used with
405 .It Ev TLS_CLIENT_NOT_AFTER
406 The time corresponding to the end of the validity period of the peer
407 certificate in the ISO 8601 format
408 .Pq e.g. Dq 2021-02-07T20:17:41Z .
409 .It Ev TLS_CLIENT_NOT_BEFORE
410 The time corresponding to the start of the validity period of the peer
411 certificate in the ISO 8601 format.
415 To auto-detect the MIME type of the response
417 looks at the file extension and consults its internal table.
418 By default the following mappings are loaded, but they can be
419 overridden or extended using the
421 configuration option.
422 If no MIME is found, the value of
426 will be used, which is
427 .Dq application/octet-stream
430 .Bl -tag -offset indent -width 14m -compact
457 Serve the current directory
458 .Bd -literal -offset indent
462 To serve the directory
464 and enable CGI scripts inside
467 .Bd -literal -offset indent
469 $ cat <<EOF > docs/cgi/hello
471 printf "20 text/plain\\r\\n"
474 $ chmod +x docs/cgi/hello
475 $ gmid -x '/cgi/*' docs
478 The following is an example of a possible configuration for a site
479 that enables only TLSv1.3, adds a mime type for the file extension
480 "rtf" and defines two virtual host:
481 .Bd -literal -offset indent
482 ipv6 on # enable ipv6
486 mime "application/rtf" "rtf"
488 server "example.com" {
489 cert "/path/to/cert.pem"
490 key "/path/to/key.pem"
491 root "/var/gemini/example.com"
494 server "it.example.com" {
495 cert "/path/to/cert.pem"
496 key "/path/to/key.pem"
497 root "/var/gemini/it.example.com"
503 Yet another example, showing how to enable a
508 .Bd -literal -offset indent
512 server "example.com" {
513 cert "/path/to/cert.pem"
514 key "/path/to/key.pem"
515 root "/example.com" # in the /var/gemini chroot
517 location "/static/*" {
526 .Dq Flexible and Economical
527 UTF-8 decoder written by
528 .An Bjoern Hoehrmann .
533 program was written by
534 .An Omar Polo Aq Mt op@omarpolo.com .
538 The root directories of all virtual hosts are opened during the daemon
539 startup; this means that if a root directory gets deleted and then
542 won't be able to serve files inside that directory until a restart.
543 This restriction applies only to the root directories and not their content.
545 a %2F sequence is indistinguishable from a literal slash: this is not
548 a %00 sequence is treated as invalid character and thus rejected.
