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
37 is a simple and minimal gemini server that can serve static files and
39 It can run without a configuration file with a limited set of features
43 rereads the configuration file when it receives
46 The options are as follows:
49 Specify the configuration file.
51 Stays and logs on the foreground.
53 Check that the configuration is valid, but don't start the server.
56 If no configuration file is given,
58 will look for the following options
62 .It Fl d Pa certs-path
63 Directory where certificates for the config-less mode are stored.
65 .Pa $XDG_DATA_HOME/gmid ,
67 .Pa ~/.local/share/gmid .
69 The hostname, by default
71 Certificates for the given
73 are searched inside the
75 directory given with the
81 .Pa hostname.key.pem .
82 If a certificate or key don't exists for a given hostname they
83 will be automatically generated.
85 Print the usage and exit.
87 The port to listen on, by default 1965.
92 options increase the verbosity.
94 Enable execution of CGI scripts.
95 See the description of the
102 Cannot be provided more than once.
104 The root directory to serve.
105 By default the current working directory is assumed.
107 .Sh CONFIGURATION FILE
108 The configuration file is divided into two sections:
110 .It Sy Global Options
114 Virtual hosts definition.
117 Within the sections, empty lines are ignored and comments can be put
118 anywhere in the file using a hash mark
120 and extend to the end of the current line.
121 A boolean is either the symbol
125 A string is a sequence of characters wrapped in double quotes,
129 .It Ic chroot Pa path
131 the process to the given
133 The daemon has to be run with root privileges and thus the option
135 needs to be provided, so privileges can be dropped.
138 will enter the chroot after loading the TLS keys, but before opening
139 the virtual host root directories.
140 It's recommended to keep the TLS keys outside the chroot.
145 Enable or disable IPv6 support.
147 .It Ic mime Ar mime-type Ar file-extension
148 Add a mapping for the given
152 Both argument are strings.
153 .It Ic port Ar portno
154 The port to listen on.
156 .It Ic prefork Ar number
157 Run the specified number of server processes.
158 This increases the performance and prevents delays when connecting to
161 runs 3 server processes by default, when not in config-less mode.
162 The maximum number allowed is 16.
163 .It Ic protocols Ar string
164 Specify the TLS protocols to enable.
166 .Xr tls_config_parse_protocols 3
167 for the valid protocol string values.
168 By default, both TLSv1.3 and TLSv1.2 are enabled.
171 to enable only TLSv1.3.
172 .It Ic user Ar string
173 Run the daemon as the given user.
176 Every virtual host is defined by a
180 .It Ic server Ar hostname Brq ...
181 Match the server name using shell globbing rules.
182 This can be an explicit name,
183 .Ar www.example.com ,
184 or a name including a wildcards,
188 Followed by a block of options that is enclosed in curly brackets:
190 .It Ic auto Ic index Ar bool
191 If no index file is found, automatically generate a directory listing.
192 It's disabled by default.
193 .It Ic block Op Ic return Ar code Op Ar meta
194 Send a reply and close the connection;
200 .Dq temporary failure
204 is in the 3x range, then
209 the following special sequences are replaced:
212 is replaced with a single
215 is replaced with the request path.
217 is replaced with the query string of the request.
219 is replaced with the server port.
221 is replaced with the server name.
224 Path to the certificate to use for this server.
227 should contain a PEM encoded certificate.
228 This option is mandatory.
230 Execute CGI scripts that matches
232 using shell globbing rules.
233 .It Ic default type Ar string
234 Set the default media type that is used if the media type for a
235 specified extension is not found.
236 If not specified, the
239 .Dq application/octet-stream .
240 .It Ic entrypoint Pa path
241 Handle all the requests for the current virtual host using the
244 .It Ic env Ar name Ar value
245 Set the environment variable
249 when executing CGI scripts.
250 Can be provided more than once.
251 .It Ic index Ar string
252 Set the directory index file.
253 If not specified, it defaults to
256 Specify the private key to use for this server.
259 should contain a PEM encoded private key.
260 This option is mandatory.
261 .It Ic lang Ar string
262 Specify the language tag for the text/gemini content served.
265 parameter will be added in the response.
266 .It Ic location Pa path Brq ...
267 Specify server configuration rules for a specific location.
270 argument will be matched against the request path with shell globbing
272 In case of multiple location statements in the same context, the first
273 matching location will be put into effect and the later ones ignored.
274 Therefore is advisable to match for more specific paths first and for
275 generic ones later on.
278 section may include most of the server configuration rules
280 .Ic cert , Ic env , Ic key , Ic root , Ic location ,
281 .Ic entrypoint No and Ic cgi .
282 .It Ic root Pa directory
283 Specify the root directory for this server.
284 This option is mandatory.
285 It's relative to the chroot, if enabled.
286 .It Ic require Ic client Ic ca Pa path
287 Allow requests only from clients that provide a certificate signed by
288 the CA certificate in
290 It needs to be a PEM-encoded certificate and it's not relative to the
292 .It Ic strip Ar number
295 components from the beginning of the path.
296 It's only considered for the
298 parameter in the scope of a
302 When a request for an executable file matches the
304 rule, that file will be execute and its output fed to the client.
306 The CGI scripts are executed in the directory they reside and inherit
309 with these additional variables set:
311 .It Ev GATEWAY_INTERFACE
313 .It Ev GEMINI_DOCUMENT_ROOT
314 The root directory of the virtual host.
315 .It Ev GEMINI_SCRIPT_FILENAME
316 Full path to the CGI script being executed.
318 The full IRI of the request.
319 .It Ev GEMINI_URL_PATH
320 The path of the request.
322 The portion of the requested path that is derived from the the IRI
323 path hierarchy following the part that identifies the script itself.
325 .It Ev PATH_TRANSLATED
326 Present if and only if
329 It represent the translation of the
332 builds this by appending the
334 to the virtual host directory root.
336 The decoded query string.
337 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
338 Textual representation of the client IP.
339 .It Ev REQUEST_METHOD
340 This is present only for RFC3875 (CGI) compliance.
341 It's always set to the empty string.
345 that identifies the current CGI script.
347 The name of the server
349 The port the server is listening on.
350 .It Ev SERVER_PROTOCOL
352 .It Ev SERVER_SOFTWARE
353 The name and version of the server, i.e.
356 The string "Certificate" if the client used a certificate, otherwise
359 The subject of the client certificate if provided, otherwise unset.
360 .It Ev TLS_CLIENT_ISSUER
361 The is the issuer of the client certificate if provided, otherwise
363 .It Ev TLS_CLIENT_HASH
364 The hash of the client certificate if provided, otherwise unset.
368 The TLS version negotiated with the peer.
370 The cipher suite negotiated with the peer.
371 .It Ev TLS_CIPHER_STRENGTH
372 The strength in bits for the symmetric cipher that is being used with
374 .It Ev TLS_CLIENT_NOT_AFTER
375 The time corresponding to the end of the validity period of the peer
376 certificate in the ISO 8601 format
377 .Pq e.g. Dq 2021-02-07T20:17:41Z .
378 .It Ev TLS_CLIENT_NOT_BEFORE
379 The time corresponding to the start of the validity period of the peer
380 certificate in the ISO 8601 format.
384 To auto-detect the MIME type of the response
386 looks at the file extension and consults its internal table.
387 By default the following mappings are loaded, but they can be
388 overridden or extended using the
390 configuration option.
391 If no MIME is found, the value of
395 will be used, which is
396 .Dq application/octet-stream
399 .Bl -tag -offset indent -width 14m -compact
426 Serve the current directory
427 .Bd -literal -offset indent
431 To serve the directory
433 and enable CGI scripts inside
436 .Bd -literal -offset indent
438 $ cat <<EOF > docs/cgi/hello
440 printf "20 text/plain\\r\\n"
443 $ chmod +x docs/cgi/hello
444 $ gmid -x '/cgi/*' docs
447 The following is an example of a possible configuration for a site
448 that enables only TLSv1.3, adds a mime type for the file extension
449 "rtf" and defines two virtual host:
450 .Bd -literal -offset indent
451 ipv6 on # enable ipv6
455 mime "application/rtf" "rtf"
457 server "example.com" {
458 cert "/path/to/cert.pem"
459 key "/path/to/key.pem"
460 root "/var/gemini/example.com"
463 server "it.example.com" {
464 cert "/path/to/cert.pem"
465 key "/path/to/key.pem"
466 root "/var/gemini/it.example.com"
472 Yet another example, showing how to enable a
477 .Bd -literal -offset indent
481 server "example.com" {
482 cert "/path/to/cert.pem"
483 key "/path/to/key.pem"
484 root "/example.com" # in the /var/gemini chroot
486 location "/static/*" {
495 .Dq Flexible and Economical
496 UTF-8 decoder written by
497 .An Bjoern Hoehrmann .
502 program was written by
503 .An Omar Polo Aq Mt op@omarpolo.com .
507 The root directories of all virtual hosts are opened during the daemon
508 startup; this means that if a root directory gets deleted and then
511 won't be able to serve files inside that directory until a restart.
512 This restriction applies only to the root directories and not their content.
514 a %2F sequence is indistinguishable from a literal slash: this is not
517 a %00 sequence is treated as invalid character and thus rejected.
