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
35 is a simple and minimal gemini server that can serve static files and
37 It can run without a configuration file with a limited set of features
39 If a configuration file is given, no other flags shall be given,
45 The options are as follows:
48 Specify the configuration file.
50 Stays and logs on the foreground.
52 Check that the configuration is valid, but don't start the server.
55 If no configuration file is given,
57 will look for the following options
61 .It Fl d Pa certs-path
62 Directory where certificates for the config-less mode are stored.
64 .Pa $XDG_DATA_HOME/gmid ,
66 .Pa ~/.local/share/gmid .
68 The hostname, by default
70 Certificates for the given
72 are searched inside the
74 directory given with the
80 .Pa hostname.key.pem .
81 If a certificate and key doesn't exists for a given hostname they
82 will be automatically generated.
84 Print the usage and exit.
86 The port to listen on, by default 1965.
88 Increase the verbosity of the logs.
90 Enable execution of CGI scripts.
91 See the description of the
98 Cannot be provided more than once.
100 The root directory to serve.
101 By default the current working directory is assumed.
103 .Sh CONFIGURATION FILE
104 The configuration file is divided into two sections:
106 .It Sy Global Options
110 Virtual hosts definition.
113 Within the sections, empty lines are ignored and comments can be put
114 anywhere in the file using a hash mark
116 and extend to the end of the current line.
117 A boolean is either the symbol
121 A string is a sequence of characters wrapped in double quotes,
126 Enable or disable IPv6 support.
128 .It Ic port Ar portno
129 The port to listen on.
131 .It Ic protocols Ar string
132 Specify the TLS protocols to enable.
134 .Xr tls_config_parse_protocols 3
135 for the valid protocol string values.
136 By default, both TLSv1.3 and TLSv1.2 are enabled.
139 to enable only TLSv1.3.
140 .It Ic mime Ar mime-type Ar file-extension
141 Add a mapping for the given
145 Both argument are strings.
146 .It Ic chroot Pa path
148 the process to the given
150 The daemon has to be run with root privileges and thus the option
152 needs to be provided, so privileges can be dropped.
155 will enter the chroot after loading the TLS keys, but before opening
156 the virtual host root directories.
157 It's recommended to keep the TLS keys outside the chroot.
161 .It Ic user Ar string
162 Run the daemon as the given user.
165 Every virtual host is defined by a
169 .It Ic server Ar hostname Brq ...
170 Match the server name using shell globbing rules.
171 This can be an explicit name,
172 .Ar www.example.com ,
173 or a name including a wildcards,
177 Followed by a block of options that is enclosed in curly brackets:
180 Path to the certificate to use for this server.
183 should contain a PEM encoded certificate.
184 This option is mandatory.
186 Specify the private key to use for this server.
189 should contain a PEM encoded private key.
190 This option is mandatory.
191 .It Ic root Pa directory
192 Specify the root directory for this server.
193 This option is mandatory.
194 It's relative to the chroot, if enabled.
196 Enable the execution of CGI scripts if
198 is a prefix of the user request string.
199 An empty path "" will effectively enable the execution of any file
200 with the executable bit set inside the root directory.
201 .It Ic default type Ar string
202 Set the default media type that is used if the media type for a
203 specified extension is not found.
204 If not specified, the
207 .Dq application/octet-stream .
208 .It Ic lang Ar string
209 Specify the language tag for the text/gemini content served.
212 parameter will be added in the response.
213 .It Ic index Ar string
214 Set the directory index file.
215 If not specified, it defaults to
217 .It Ic auto Ic index Ar bool
218 If no index file is found, automatically generate a directory listing.
219 It's disabled by default.
220 .It Ic location Pa path Brq ...
221 Specify server configuration rules for a specific location.
224 argument will be matched against the request path with shell globbing
226 In case of multiple location statements in the same context, the first
227 matching location will be put into effect and the later ones ignored.
228 Therefore is advisable to match for more specific paths first and for
229 generic ones later on.
232 section may include most of the server configuration rules
234 .Ic cert , Ic key , Ic root , Ic location No and Ic cgi .
237 When CGI scripts are enabled for a directory, a request for an
238 executable file will execute it and fed its output to the client.
240 The CGI scripts are executed in the root directory of the virtual
241 host, or in the served directory if run without config, and inherits
244 with these additional variables set:
246 .It Ev GATEWAY_INTERFACE
248 .It Ev SERVER_PROTOCOL
250 .It Ev SERVER_SOFTWARE
256 This variable is not available when operating without a configuration.
258 The (public) path to the script, e.g.
259 .Pa "/cgi-bin/example.cgi"
260 .It Ev SCRIPT_EXECUTABLE
261 The full path to the executable.
263 The user request (without the query parameters.)
264 .It Ev REQUEST_RELATIVE
265 The request relative to the script.
267 The query parameters.
269 The remote IP address.
271 The remote IP address.
273 The root directory being served, the one provided with the
277 or the root directory of the virtual host.
279 The string "Certificate" if the client used a certificate, otherwise
282 The subject of the client certificate if provided, otherwise unset.
283 .It Ev TLS_CLIENT_ISSUER
284 The is the issuer of the client certificate if provided, otherwise
286 .It Ev TLS_CLIENT_HASH
287 The hash of the client certificate if provided, otherwise unset.
288 The format is "ALGO:HASH".
291 Let's say you have a script in
293 and the user request is
294 .Pa /cgi-bin/script/foo/bar?quux .
299 .Ev SCRIPT_EXECUTABLE
301 .Pa $DOCUMENT_ROOT/cgi-bin/script ,
304 .Pa cgi-bin/script/foo/bar ,
313 To auto-detect the MIME type of the response
315 looks at the file extension and consults its internal table.
316 By default the following mappings are loaded, but they can be
317 overridden or extended using the
319 configuration option.
320 If no MIME is found, the value of
324 will be used, which is
325 .Dq application/octet-stream
328 .Bl -tag -offset indent -width 14m -compact
351 Serve the current directory
352 .Bd -literal -offset indent
356 To serve the directory
358 and enable CGI scripts inside
361 .Bd -literal -offset indent
363 $ cat <<EOF > cgi/hello
365 printf "20 text/plain\\r\\n"
368 $ chmod +x docs/cgi/hello
372 Note that the argument to the
378 since it's relative to the document root.
380 The following is an example of a possible configuration for a site
381 that enables only TLSv1.3, adds a mime type for the file extension
382 "rtf" and defines two virtual host:
383 .Bd -literal -offset indent
384 ipv6 on # enable ipv6
388 mime "application/rtf" "rtf"
390 server "example.com" {
391 cert "/path/to/cert.pem"
392 key "/path/to/key.pem"
393 root "/var/gemini/example.com"
396 server "it.example.com" {
397 cert "/path/to/cert.pem"
398 key "/path/to/key.pem"
399 root "/var/gemini/it.example.com"
405 Yet another example, showing how to enable a
410 .Bd -literal -offset indent
414 server "example.com" {
415 cert "/path/to/cert.pem"
416 key "/path/to/key.pem"
417 root "/example.com" # in the /var/gemini chroot
419 location "/static/" {
428 .Dq Flexible and Economical
429 UTF-8 decoder written by
430 .An Bjoern Hoehrmann .
435 program was written by
436 .An Omar Polo Aq Mt op@omarpolo.com .
440 The root directories of all virtual hosts are opened during the daemon
441 startup; this means that if a root directory gets deleted and then
444 won't be able to serve files inside that directory until a restart.
445 This restriction applies only to the root directories and not their content.
447 a %2F sequence is indistinguishable from a literal slash: this is not
450 a %00 sequence is treated as invalid character and thus rejected.
