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.
93 .It Fl V , Fl -version
94 Print the version and exit.
99 options increase the verbosity.
101 Enable execution of CGI scripts.
102 See the description of the
104 option in the section
109 Cannot be provided more than once.
111 The root directory to serve.
112 By default the current working directory is assumed.
114 .Sh CONFIGURATION FILE
115 The configuration file is divided into two sections:
117 .It Sy Global Options
121 Virtual hosts definition.
124 Within the sections, empty lines are ignored and comments can be put
125 anywhere in the file using a hash mark
127 and extend to the end of the current line.
128 A boolean is either the symbol
132 A string is a sequence of characters wrapped in double quotes,
136 .It Ic chroot Pa path
138 the process to the given
140 The daemon has to be run with root privileges and thus the option
142 needs to be provided, so privileges can be dropped.
145 will enter the chroot after loading the TLS keys, but before opening
146 the virtual host root directories.
147 It's recommended to keep the TLS keys outside the chroot.
152 Enable or disable IPv6 support.
154 .It Ic mime Ar mime-type Ar file-extension
155 Add a mapping for the given
159 Both argument are strings.
160 .It Ic port Ar portno
161 The port to listen on.
163 .It Ic prefork Ar number
164 Run the specified number of server processes.
165 This increases the performance and prevents delays when connecting to
168 runs 3 server processes by default, when not in config-less mode.
169 The maximum number allowed is 16.
170 .It Ic protocols Ar string
171 Specify the TLS protocols to enable.
173 .Xr tls_config_parse_protocols 3
174 for the valid protocol string values.
175 By default, both TLSv1.3 and TLSv1.2 are enabled.
178 to enable only TLSv1.3.
179 .It Ic user Ar string
180 Run the daemon as the given user.
183 Every virtual host is defined by a
187 .It Ic server Ar hostname Brq ...
188 Match the server name using shell globbing rules.
189 This can be an explicit name,
190 .Ar www.example.com ,
191 or a name including a wildcards,
195 Followed by a block of options that is enclosed in curly brackets:
198 Specify an additional alias
201 .It Ic auto Ic index Ar bool
202 If no index file is found, automatically generate a directory listing.
203 It's disabled by default.
204 .It Ic block Op Ic return Ar code Op Ar meta
205 Send a reply and close the connection;
211 .Dq temporary failure
215 is in the 3x range, then
220 the following special sequences are replaced:
221 .Bl -tag -width Ds -compact
223 is replaced with a single
226 is replaced with the request path.
228 is replaced with the query string of the request.
230 is replaced with the server port.
232 is replaced with the server name.
235 Path to the certificate to use for this server.
238 should contain a PEM encoded certificate.
239 This option is mandatory.
241 Execute CGI scripts that matches
243 using shell globbing rules.
244 .It Ic default type Ar string
245 Set the default media type that is used if the media type for a
246 specified extension is not found.
247 If not specified, the
250 .Dq application/octet-stream .
251 .It Ic entrypoint Pa path
252 Handle all the requests for the current virtual host using the
255 .It Ic env Ar name Ar value
256 Set the environment variable
260 when executing CGI scripts.
261 Can be provided more than once.
262 .\" don't document the "spawn <prog>" form because it probably won't
264 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Ar port Oc
265 Enable FastCGI instead of serving files.
268 can either be a UNIX domain socket or a TCP socket.
269 If the FastCGI application is listening on a UNIX domain socket,
271 is a local path name within the
277 keyword must be provided and
279 is interpreted as a hostname or an IP address.
281 can be either a port number or the name of a service enclosed in
283 If it's not specified defaults to 9000.
284 .It Ic index Ar string
285 Set the directory index file.
286 If not specified, it defaults to
289 Specify the private key to use for this server.
292 should contain a PEM encoded private key.
293 This option is mandatory.
294 .It Ic lang Ar string
295 Specify the language tag for the text/gemini content served.
298 parameter will be added in the response.
299 .It Ic location Pa path Brq ...
300 Specify server configuration rules for a specific location.
303 argument will be matched against the request path with shell globbing
305 In case of multiple location statements in the same context, the first
306 matching location will be put into effect and the later ones ignored.
307 Therefore is advisable to match for more specific paths first and for
308 generic ones later on.
311 section may include most of the server configuration rules
313 .Ic alias , Ic cert , Ic env , Ic key , Ic location ,
314 .Ic entrypoint No and Ic cgi .
316 Enable or disable the logging for the current server or location block.
317 .It Ic param Ar name Ar value
323 .It Ic root Pa directory
324 Specify the root directory for this server.
325 It's relative to the chroot, if enabled.
326 .It Ic require Ic client Ic ca Pa path
327 Allow requests only from clients that provide a certificate signed by
328 the CA certificate in
330 It needs to be a PEM-encoded certificate and it's not relative to the
332 .It Ic strip Ar number
335 components from the beginning of the path before doing a lookup in the
337 It's also considered for the
339 parameter in the scope of a
343 When a request for an executable file matches the
345 rule, that file will be execute and its output fed to the client.
347 The CGI scripts are executed in the directory they reside and inherit
350 with these additional variables set:
352 .It Ev GATEWAY_INTERFACE
354 .It Ev GEMINI_DOCUMENT_ROOT
355 The root directory of the virtual host.
356 .It Ev GEMINI_SCRIPT_FILENAME
357 Full path to the CGI script being executed.
359 The full IRI of the request.
360 .It Ev GEMINI_URL_PATH
361 The path of the request.
363 The portion of the requested path that is derived from the the IRI
364 path hierarchy following the part that identifies the script itself.
366 .It Ev PATH_TRANSLATED
367 Present if and only if
370 It represent the translation of the
373 builds this by appending the
375 to the virtual host directory root.
377 The decoded query string.
378 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
379 Textual representation of the client IP.
380 .It Ev REQUEST_METHOD
381 This is present only for RFC3875 (CGI) compliance.
382 It's always set to the empty string.
386 that identifies the current CGI script.
388 The name of the server
390 The port the server is listening on.
391 .It Ev SERVER_PROTOCOL
393 .It Ev SERVER_SOFTWARE
394 The name and version of the server, i.e.
397 The string "Certificate" if the client used a certificate, otherwise
400 The subject of the client certificate if provided, otherwise unset.
401 .It Ev TLS_CLIENT_ISSUER
402 The is the issuer of the client certificate if provided, otherwise
404 .It Ev TLS_CLIENT_HASH
405 The hash of the client certificate if provided, otherwise unset.
409 The TLS version negotiated with the peer.
411 The cipher suite negotiated with the peer.
412 .It Ev TLS_CIPHER_STRENGTH
413 The strength in bits for the symmetric cipher that is being used with
415 .It Ev TLS_CLIENT_NOT_AFTER
416 The time corresponding to the end of the validity period of the peer
417 certificate in the ISO 8601 format
418 .Pq e.g. Dq 2021-02-07T20:17:41Z .
419 .It Ev TLS_CLIENT_NOT_BEFORE
420 The time corresponding to the start of the validity period of the peer
421 certificate in the ISO 8601 format.
425 optionally supports FastCGI.
428 rule must be present in a server or location block.
429 Then, all requests matching that server or location will be handled
430 via the specified FastCGI backend.
432 By default the following variables
434 are sent, and carry the same semantics as with CGI.
435 More parameters can be added with the
472 TLS_CLIENT_NOT_BEFORE
477 To auto-detect the MIME type of the response
479 looks at the file extension and consults its internal table.
480 By default the following mappings are loaded, but they can be
481 overridden or extended using the
483 configuration option.
484 If no MIME is found, the value of
488 will be used, which is
489 .Dq application/octet-stream
492 .Bl -tag -offset indent -width 14m -compact
519 Serve the current directory
520 .Bd -literal -offset indent
524 To serve the directory
526 and enable CGI scripts inside
529 .Bd -literal -offset indent
531 $ cat <<EOF > docs/cgi/hello
533 printf "20 text/plain\\r\\n"
536 $ chmod +x docs/cgi/hello
537 $ gmid -x '/cgi/*' docs
540 The following is an example of a possible configuration for a site
541 that enables only TLSv1.3, adds a mime type for the file extension
542 "rtf" and defines two virtual host:
543 .Bd -literal -offset indent
544 ipv6 on # enable ipv6
548 mime "application/rtf" "rtf"
550 server "example.com" {
551 cert "/path/to/cert.pem"
552 key "/path/to/key.pem"
553 root "/var/gemini/example.com"
556 server "it.example.com" {
557 cert "/path/to/cert.pem"
558 key "/path/to/key.pem"
559 root "/var/gemini/it.example.com"
565 Yet another example, showing how to enable a
570 .Bd -literal -offset indent
574 server "example.com" {
575 cert "/path/to/cert.pem"
576 key "/path/to/key.pem"
577 root "/example.com" # in the /var/gemini chroot
579 location "/static/*" {
588 .Dq Flexible and Economical
589 UTF-8 decoder written by
590 .An Bjoern Hoehrmann .
595 program was written by
596 .An Omar Polo Aq Mt op@omarpolo.com .
600 The root directories of all virtual hosts are opened during the daemon
601 startup; this means that if a root directory gets deleted and then
604 won't be able to serve files inside that directory until a restart.
605 This restriction applies only to the root directories and not their content.
607 a %2F sequence is indistinguishable from a literal slash: this is not
610 a %00 sequence is treated as invalid character and thus rejected.
