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 and key doesn'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.
89 Increase the verbosity of the logs.
91 Enable execution of CGI scripts.
92 See the description of the
99 Cannot be provided more than once.
101 The root directory to serve.
102 By default the current working directory is assumed.
104 .Sh CONFIGURATION FILE
105 The configuration file is divided into two sections:
107 .It Sy Global Options
111 Virtual hosts definition.
114 Within the sections, empty lines are ignored and comments can be put
115 anywhere in the file using a hash mark
117 and extend to the end of the current line.
118 A boolean is either the symbol
122 A string is a sequence of characters wrapped in double quotes,
127 Enable or disable IPv6 support.
129 .It Ic port Ar portno
130 The port to listen on.
132 .It Ic protocols Ar string
133 Specify the TLS protocols to enable.
135 .Xr tls_config_parse_protocols 3
136 for the valid protocol string values.
137 By default, both TLSv1.3 and TLSv1.2 are enabled.
140 to enable only TLSv1.3.
141 .It Ic mime Ar mime-type Ar file-extension
142 Add a mapping for the given
146 Both argument are strings.
147 .It Ic chroot Pa path
149 the process to the given
151 The daemon has to be run with root privileges and thus the option
153 needs to be provided, so privileges can be dropped.
156 will enter the chroot after loading the TLS keys, but before opening
157 the virtual host root directories.
158 It's recommended to keep the TLS keys outside the chroot.
162 .It Ic user Ar string
163 Run the daemon as the given user.
166 Every virtual host is defined by a
170 .It Ic server Ar hostname Brq ...
171 Match the server name using shell globbing rules.
172 This can be an explicit name,
173 .Ar www.example.com ,
174 or a name including a wildcards,
178 Followed by a block of options that is enclosed in curly brackets:
181 Path to the certificate to use for this server.
184 should contain a PEM encoded certificate.
185 This option is mandatory.
187 Specify the private key to use for this server.
190 should contain a PEM encoded private key.
191 This option is mandatory.
192 .It Ic root Pa directory
193 Specify the root directory for this server.
194 This option is mandatory.
195 It's relative to the chroot, if enabled.
197 Execute CGI scripts that matches
199 using shell globbing rules.
200 .It Ic default type Ar string
201 Set the default media type that is used if the media type for a
202 specified extension is not found.
203 If not specified, the
206 .Dq application/octet-stream .
207 .It Ic lang Ar string
208 Specify the language tag for the text/gemini content served.
211 parameter will be added in the response.
212 .It Ic index Ar string
213 Set the directory index file.
214 If not specified, it defaults to
216 .It Ic auto Ic index Ar bool
217 If no index file is found, automatically generate a directory listing.
218 It's disabled by default.
219 .It Ic location Pa path Brq ...
220 Specify server configuration rules for a specific location.
223 argument will be matched against the request path with shell globbing
225 In case of multiple location statements in the same context, the first
226 matching location will be put into effect and the later ones ignored.
227 Therefore is advisable to match for more specific paths first and for
228 generic ones later on.
231 section may include most of the server configuration rules
233 .Ic cert , Ic key , Ic root , Ic location No and Ic cgi .
236 When a request for an executable file matches the
238 rule, that file will be execute and its output fed to the client.
240 The CGI scripts are executed in the directory they reside and inherit
243 with these additional variables set:
245 .It Ev GATEWAY_INTERFACE
247 .It Ev GEMINI_DOCUMENT_ROOT
248 The root directory of the virtual host.
249 .It Ev GEMINI_SCRIPT_FILENAME
250 Full path to the CGI script being executed.
252 The full IRI of the request.
253 .It Ev GEMINI_URL_PATH
254 The path of the request.
256 The portion of the requested path that is derived from the the IRI
257 path hierarchy following the part that identifies the script itself.
259 .It Ev PATH_TRANSLATED
260 Present if and only if
263 It represent the translation of the
266 builds this by appending the
268 to the virtual host directory root.
270 The decoded query string.
271 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
272 Textual representation of the client IP.
273 .It Ev REQUEST_METHOD
274 This is present only for RFC3875 (CGI) compliance.
275 It's always set to the empty string.
279 that identifies the current CGI script.
281 The name of the server
283 The port the server is listening on.
284 .It Ev SERVER_PROTOCOL
286 .It Ev SERVER_SOFTWARE
287 The name and version of the server, i.e.
290 The string "Certificate" if the client used a certificate, otherwise
293 The subject of the client certificate if provided, otherwise unset.
294 .It Ev TLS_CLIENT_ISSUER
295 The is the issuer of the client certificate if provided, otherwise
297 .It Ev TLS_CLIENT_HASH
298 The hash of the client certificate if provided, otherwise unset.
304 To auto-detect the MIME type of the response
306 looks at the file extension and consults its internal table.
307 By default the following mappings are loaded, but they can be
308 overridden or extended using the
310 configuration option.
311 If no MIME is found, the value of
315 will be used, which is
316 .Dq application/octet-stream
319 .Bl -tag -offset indent -width 14m -compact
342 Serve the current directory
343 .Bd -literal -offset indent
347 To serve the directory
349 and enable CGI scripts inside
352 .Bd -literal -offset indent
354 $ cat <<EOF > cgi/hello
356 printf "20 text/plain\\r\\n"
359 $ chmod +x docs/cgi/hello
363 The following is an example of a possible configuration for a site
364 that enables only TLSv1.3, adds a mime type for the file extension
365 "rtf" and defines two virtual host:
366 .Bd -literal -offset indent
367 ipv6 on # enable ipv6
371 mime "application/rtf" "rtf"
373 server "example.com" {
374 cert "/path/to/cert.pem"
375 key "/path/to/key.pem"
376 root "/var/gemini/example.com"
379 server "it.example.com" {
380 cert "/path/to/cert.pem"
381 key "/path/to/key.pem"
382 root "/var/gemini/it.example.com"
388 Yet another example, showing how to enable a
393 .Bd -literal -offset indent
397 server "example.com" {
398 cert "/path/to/cert.pem"
399 key "/path/to/key.pem"
400 root "/example.com" # in the /var/gemini chroot
402 location "/static/*" {
411 .Dq Flexible and Economical
412 UTF-8 decoder written by
413 .An Bjoern Hoehrmann .
418 program was written by
419 .An Omar Polo Aq Mt op@omarpolo.com .
423 The root directories of all virtual hosts are opened during the daemon
424 startup; this means that if a root directory gets deleted and then
427 won't be able to serve files inside that directory until a restart.
428 This restriction applies only to the root directories and not their content.
430 a %2F sequence is indistinguishable from a literal slash: this is not
433 a %00 sequence is treated as invalid character and thus rejected.
