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 25 2021$
19 .Nd dead simple zero configuration 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,
46 fully supports IRIs (Internationalized Resource Identifiers, see
49 The options are as follows:
52 Specify the configuration file.
54 Stays and logs on the foreground.
56 Check that the configuration is valid, but don't start the server.
59 If no configuration file is given,
61 will look for the following options
65 .It Fl d Pa certs-path
66 Directory where certificates for the config-less mode are stored.
68 .Pa $XDG_DATA_HOME/gmid ,
70 .Pa ~/.local/share/gmid .
72 The hostname, by default
74 Certificates for the given
76 are searched inside the
78 directory given with the
84 .Pa hostname.key.pem .
85 If a certificate and key doesn't exists for a given hostname they
86 would be automatically generated.
88 Print the usage and exit.
90 The port to listen on, by default 1965.
92 Increase the verbosity of the logs.
94 Enable execution of CGI scripts.
95 See the description of the
103 Cannot be provided more than once.
105 The root directory to serve.
106 By default the current working directory is assumed.
108 .Sh CONFIGURATION FILE
109 The configuration file is divided into two sections:
111 .It Sy Global Options
115 Virtual hosts definition.
118 Within the sections, empty lines are ignored and comments can be put
119 anywhere in the file using a hash mark
121 and extend to the end of the current line.
122 A boolean is either the symbol
126 A string is a sequence of characters wrapped in double quotes,
131 Enable or disable IPv6 support.
133 .It Ic port Ar portno
134 The port to listen on.
136 .It Ic protocols Ar string
137 Specify the TLS protocols to enable.
139 .Xr tls_config_parse_protocols 3
140 for the valid protocol string values.
141 By default, both TLSv1.3 and TLSv1.2 are used.
144 to enable only TLSv1.3.
145 .It Ic mime Ar mime-type Ar file-extension
146 Add a mapping for the given
150 Both argument are strings.
151 .It Ic chroot Pa path
153 the process to the given
155 The daemon has to be run with root privileges and thus the option
157 needs to be provided, so
159 can drop the privileges.
160 Note that they are dropped after loading the TLS keys, so it's
161 recommended to put those outside the chroot.
165 .It Ic user Ar string
166 Run the daemon as the given user.
169 Every virtual host is defined by a
173 .It Ic server Ar hostname Brq ...
174 Match the server name using shell globbing rules.
175 This can be an explicit name,
176 .Ar www.example.com ,
177 or a name including a wildcards,
181 Followed by a block of options that is enclosed in curly brackets:
184 Path to the certificate to use for this server.
187 should contain a PEM encoded certificate.
188 This option is mandatory.
190 Specify the private key to use for this server.
193 should contain a PEM encoded private key.
194 This option is mandatory.
195 .It Ic root Pa directory
196 Specify the root directory for this server.
197 This option is mandatory.
198 It's relative to the chroot, if enabled.
200 Enable the execution of CGI scripts if
202 is a prefix of the user request string.
203 An empty path "" will effectively enable the execution of any file
204 with the executable bit set inside the root directory.
205 .It Ic default type Ar string
206 Set the default media type that is used if the media type for a
207 specified extension is not found.
208 If not specified, the
211 .Dq application/octet-stream .
212 .It Ic lang Ar string
213 Specify the language tag for the text/gemini content served.
216 parameter will be added in the response.
217 .It Ic index Ar string
218 Set the directory index file.
219 If not specified, it defaults to
221 .It Ic auto Ic index Ar bool
222 If no index file is found, automatically generate a directory listing.
223 It's disabled by default.
224 .It Ic location Pa path Brq ...
225 Specify server configuration rules for a specific location.
228 argument will be matched against the request path with shell globbing
230 In case of multiple location statements in the same context, the last
231 matching location will be put into effect.
232 Therefore is advisable to match for a generic paths first and for more
233 specific ones later on.
236 section may include most of the server configuration rules
238 .Ic cert , Ic key , Ic root , Ic location No and Ic CGI .
241 When CGI scripts are enabled for a directory, a request for an
242 executable file will execute it and fed its output to the client.
244 The CGI scripts are executed in the root directory of the virtual
245 host, or in the served directory if run without config, and inherits
248 with these additional variables set:
250 .It Ev GATEWAY_INTERFACE
252 .It Ev SERVER_PROTOCOL
254 .It Ev SERVER_SOFTWARE
260 This variable is not available when operating without a configuration.
262 The (public) path to the script, e.g.
263 .Pa "/cgi-bin/example.cgi"
264 .It Ev SCRIPT_EXECUTABLE
265 The full path to the executable.
267 The user request (without the query parameters.)
268 .It Ev REQUEST_RELATIVE
269 The request relative to the script.
271 The query parameters.
273 The remote IP address.
275 The remote IP address.
277 The root directory being served, the one provided with the
281 or the root directory of the virtual host.
283 The string "Certificate" if the client used a certificate, otherwise
286 The subject of the client certificate if provided, otherwise unset.
287 .It Ev TLS_CLIENT_ISSUER
288 The is the issuer of the client certificate if provided, otherwise
290 .It Ev TLS_CLIENT_HASH
291 The hash of the client certificate if provided, otherwise unset.
292 The format is "ALGO:HASH".
295 Let's say you have a script in
297 and the user request is
298 .Pa /cgi-bin/script/foo/bar?quux .
303 .Ev SCRIPT_EXECUTABLE
305 .Pa $DOCUMENT_ROOT/cgi-bin/script ,
308 .Pa cgi-bin/script/foo/bar ,
317 To auto-detect the MIME type of the response
319 looks at the file extension and consults its internal table.
320 By default the following mappings are loaded, but they can be
321 overridden or extended using the
323 configuration option.
324 If no MIME is found, the value of
328 will be used, which is
329 .Dq application/octet-stream
332 .Bl -tag -offset indent -width 14m -compact
355 Serve the current directory
356 .Bd -literal -offset indent
360 To serve the directory
362 and enable CGI scripts inside
365 .Bd -literal -offset indent
367 $ cat <<EOF > cgi/hello
369 printf "20 text/plain\\r\\n"
372 $ chmod +x docs/cgi/hello
376 Note that the argument to the
382 since it's relative to the document root.
384 The following is an example of a possible configuration for a site
385 that enables only TLSv1.3, adds a mime type for the file extension
386 "rtf" and defines two virtual host:
387 .Bd -literal -offset indent
388 ipv6 on # enable ipv6
392 mime "application/rtf" "rtf"
394 server "example.com" {
395 cert "/path/to/cert.pem"
396 key "/path/to/key.pem"
397 root "/var/gemini/example.com"
400 server "it.example.com" {
401 cert "/path/to/cert.pem"
402 key "/path/to/key.pem"
403 root "/var/gemini/it.example.com"
409 Yet another example, showing how to enable a
414 .Bd -literal -offset indent
418 server "example.com" {
419 cert "/path/to/cert.pem"
420 key "/path/to/key.pem"
421 root "/var/gemini/example.com"
423 location "/static/" {
432 .Dq Flexible and Economical
433 UTF-8 decoder written by
434 .An Bjoern Hoehrmann .
438 The root directories of all virtual hosts are opened during the daemon
439 startup; this means that if a root directory gets deleted and then
442 won't be able to serve files inside that directory until a restart.
443 This restriction applies only to the root directories and not their content.
445 a %2F sequence in the path part is indistinguishable from a literal
446 slash: this is not RFC3986-compliant.
448 a %00 sequence either in the path or in the query part is treated as
449 invalid character and thus rejected.
