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,
46 rereads the configuration file when it receives
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 will 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
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,
130 Enable or disable IPv6 support.
132 .It Ic port Ar portno
133 The port to listen on.
135 .It Ic protocols Ar string
136 Specify the TLS protocols to enable.
138 .Xr tls_config_parse_protocols 3
139 for the valid protocol string values.
140 By default, both TLSv1.3 and TLSv1.2 are enabled.
143 to enable only TLSv1.3.
144 .It Ic mime Ar mime-type Ar file-extension
145 Add a mapping for the given
149 Both argument are strings.
150 .It Ic chroot Pa path
152 the process to the given
154 The daemon has to be run with root privileges and thus the option
156 needs to be provided, so privileges can be dropped.
159 will enter the chroot after loading the TLS keys, but before opening
160 the virtual host root directories.
161 It's recommended to keep the TLS keys 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 Execute CGI scripts that matches
202 using shell globbing rules.
203 .It Ic default type Ar string
204 Set the default media type that is used if the media type for a
205 specified extension is not found.
206 If not specified, the
209 .Dq application/octet-stream .
210 .It Ic lang Ar string
211 Specify the language tag for the text/gemini content served.
214 parameter will be added in the response.
215 .It Ic index Ar string
216 Set the directory index file.
217 If not specified, it defaults to
219 .It Ic auto Ic index Ar bool
220 If no index file is found, automatically generate a directory listing.
221 It's disabled by default.
222 .It Ic location Pa path Brq ...
223 Specify server configuration rules for a specific location.
226 argument will be matched against the request path with shell globbing
228 In case of multiple location statements in the same context, the first
229 matching location will be put into effect and the later ones ignored.
230 Therefore is advisable to match for more specific paths first and for
231 generic ones later on.
234 section may include most of the server configuration rules
236 .Ic cert , Ic key , Ic root , Ic location No and Ic cgi .
239 When a request for an executable file matches the
241 rule, that file will be execute and its output fed to the client.
243 The CGI scripts are executed in the directory they reside and inherit
246 with these additional variables set:
248 .It Ev GATEWAY_INTERFACE
250 .It Ev GEMINI_DOCUMENT_ROOT
251 The root directory of the virtual host.
252 .It Ev GEMINI_SCRIPT_FILENAME
253 Full path to the CGI script being executed.
255 The full IRI of the request.
256 .It Ev GEMINI_URL_PATH
257 The path of the request.
259 The portion of the requested path that is derived from the the IRI
260 path hierarchy following the part that identifies the script itself.
262 .It Ev PATH_TRANSLATED
263 Present if and only if
266 It represent the translation of the
269 builds this by appending the
271 to the virtual host directory root.
273 The decoded query string.
274 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
275 Textual representation of the client IP.
276 .It Ev REQUEST_METHOD
277 This is present only for RFC3875 (CGI) compliance.
278 It's always set to the empty string.
282 that identifies the current CGI script.
284 The name of the server
286 The port the server is listening on.
287 .It Ev SERVER_PROTOCOL
289 .It Ev SERVER_SOFTWARE
290 The name and version of the server, i.e.
293 The string "Certificate" if the client used a certificate, otherwise
296 The subject of the client certificate if provided, otherwise unset.
297 .It Ev TLS_CLIENT_ISSUER
298 The is the issuer of the client certificate if provided, otherwise
300 .It Ev TLS_CLIENT_HASH
301 The hash of the client certificate if provided, otherwise unset.
307 To auto-detect the MIME type of the response
309 looks at the file extension and consults its internal table.
310 By default the following mappings are loaded, but they can be
311 overridden or extended using the
313 configuration option.
314 If no MIME is found, the value of
318 will be used, which is
319 .Dq application/octet-stream
322 .Bl -tag -offset indent -width 14m -compact
345 Serve the current directory
346 .Bd -literal -offset indent
350 To serve the directory
352 and enable CGI scripts inside
355 .Bd -literal -offset indent
357 $ cat <<EOF > cgi/hello
359 printf "20 text/plain\\r\\n"
362 $ chmod +x docs/cgi/hello
366 The following is an example of a possible configuration for a site
367 that enables only TLSv1.3, adds a mime type for the file extension
368 "rtf" and defines two virtual host:
369 .Bd -literal -offset indent
370 ipv6 on # enable ipv6
374 mime "application/rtf" "rtf"
376 server "example.com" {
377 cert "/path/to/cert.pem"
378 key "/path/to/key.pem"
379 root "/var/gemini/example.com"
382 server "it.example.com" {
383 cert "/path/to/cert.pem"
384 key "/path/to/key.pem"
385 root "/var/gemini/it.example.com"
391 Yet another example, showing how to enable a
396 .Bd -literal -offset indent
400 server "example.com" {
401 cert "/path/to/cert.pem"
402 key "/path/to/key.pem"
403 root "/example.com" # in the /var/gemini chroot
405 location "/static/*" {
414 .Dq Flexible and Economical
415 UTF-8 decoder written by
416 .An Bjoern Hoehrmann .
421 program was written by
422 .An Omar Polo Aq Mt op@omarpolo.com .
426 The root directories of all virtual hosts are opened during the daemon
427 startup; this means that if a root directory gets deleted and then
430 won't be able to serve files inside that directory until a restart.
431 This restriction applies only to the root directories and not their content.
433 a %2F sequence is indistinguishable from a literal slash: this is not
436 a %00 sequence is treated as invalid character and thus rejected.
