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,
126 .It Ic chroot Pa path
128 the process to the given
130 The daemon has to be run with root privileges and thus the option
132 needs to be provided, so privileges can be dropped.
135 will enter the chroot after loading the TLS keys, but before opening
136 the virtual host root directories.
137 It's recommended to keep the TLS keys outside the chroot.
142 Enable or disable IPv6 support.
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 port Ar portno
151 The port to listen on.
153 .It Ic prefork Ar number
154 Run the specified number of server processes.
155 This increases the performance and prevents delays when connecting to
158 runs 3 server processes by default, when not in config-less mode.
159 .It Ic protocols Ar string
160 Specify the TLS protocols to enable.
162 .Xr tls_config_parse_protocols 3
163 for the valid protocol string values.
164 By default, both TLSv1.3 and TLSv1.2 are enabled.
167 to enable only TLSv1.3.
168 .It Ic user Ar string
169 Run the daemon as the given user.
172 Every virtual host is defined by a
176 .It Ic server Ar hostname Brq ...
177 Match the server name using shell globbing rules.
178 This can be an explicit name,
179 .Ar www.example.com ,
180 or a name including a wildcards,
184 Followed by a block of options that is enclosed in curly brackets:
186 .It Ic auto Ic index Ar bool
187 If no index file is found, automatically generate a directory listing.
188 It's disabled by default.
189 .It Ic block Op Ic return Ar code Op Ar meta
190 Send a reply and close the connection;
196 .Dq temporary failure
200 is in the 3x range, then
205 the following special sequences are replaced:
208 is replaced with a single
211 is replaced with the request path.
213 is replaced with the query string of the request.
215 is replaced with the server port.
217 is replaced with the server name.
220 Path to the certificate to use for this server.
223 should contain a PEM encoded certificate.
224 This option is mandatory.
226 Execute CGI scripts that matches
228 using shell globbing rules.
229 .It Ic default type Ar string
230 Set the default media type that is used if the media type for a
231 specified extension is not found.
232 If not specified, the
235 .Dq application/octet-stream .
236 .It Ic entrypoint Pa path
237 Make the CGI script at
239 .Pq relative to the Ic root No directory
240 handle all the requests for the current virtual host
241 .It Ic index Ar string
242 Set the directory index file.
243 If not specified, it defaults to
246 Specify the private key to use for this server.
249 should contain a PEM encoded private key.
250 This option is mandatory.
251 .It Ic lang Ar string
252 Specify the language tag for the text/gemini content served.
255 parameter will be added in the response.
256 .It Ic location Pa path Brq ...
257 Specify server configuration rules for a specific location.
260 argument will be matched against the request path with shell globbing
262 In case of multiple location statements in the same context, the first
263 matching location will be put into effect and the later ones ignored.
264 Therefore is advisable to match for more specific paths first and for
265 generic ones later on.
268 section may include most of the server configuration rules
270 .Ic cert , Ic key , Ic root , Ic location ,
271 .Ic entrypoint No and Ic cgi .
272 .It Ic root Pa directory
273 Specify the root directory for this server.
274 This option is mandatory.
275 It's relative to the chroot, if enabled.
276 .It Ic strip Ar number
279 components from the beginning of the path.
280 It's only considered for the
282 parameter in the scope of a
286 When a request for an executable file matches the
288 rule, that file will be execute and its output fed to the client.
290 The CGI scripts are executed in the directory they reside and inherit
293 with these additional variables set:
295 .It Ev GATEWAY_INTERFACE
297 .It Ev GEMINI_DOCUMENT_ROOT
298 The root directory of the virtual host.
299 .It Ev GEMINI_SCRIPT_FILENAME
300 Full path to the CGI script being executed.
302 The full IRI of the request.
303 .It Ev GEMINI_URL_PATH
304 The path of the request.
306 The portion of the requested path that is derived from the the IRI
307 path hierarchy following the part that identifies the script itself.
309 .It Ev PATH_TRANSLATED
310 Present if and only if
313 It represent the translation of the
316 builds this by appending the
318 to the virtual host directory root.
320 The decoded query string.
321 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
322 Textual representation of the client IP.
323 .It Ev REQUEST_METHOD
324 This is present only for RFC3875 (CGI) compliance.
325 It's always set to the empty string.
329 that identifies the current CGI script.
331 The name of the server
333 The port the server is listening on.
334 .It Ev SERVER_PROTOCOL
336 .It Ev SERVER_SOFTWARE
337 The name and version of the server, i.e.
340 The string "Certificate" if the client used a certificate, otherwise
343 The subject of the client certificate if provided, otherwise unset.
344 .It Ev TLS_CLIENT_ISSUER
345 The is the issuer of the client certificate if provided, otherwise
347 .It Ev TLS_CLIENT_HASH
348 The hash of the client certificate if provided, otherwise unset.
354 To auto-detect the MIME type of the response
356 looks at the file extension and consults its internal table.
357 By default the following mappings are loaded, but they can be
358 overridden or extended using the
360 configuration option.
361 If no MIME is found, the value of
365 will be used, which is
366 .Dq application/octet-stream
369 .Bl -tag -offset indent -width 14m -compact
392 Serve the current directory
393 .Bd -literal -offset indent
397 To serve the directory
399 and enable CGI scripts inside
402 .Bd -literal -offset indent
404 $ cat <<EOF > cgi/hello
406 printf "20 text/plain\\r\\n"
409 $ chmod +x docs/cgi/hello
413 The following is an example of a possible configuration for a site
414 that enables only TLSv1.3, adds a mime type for the file extension
415 "rtf" and defines two virtual host:
416 .Bd -literal -offset indent
417 ipv6 on # enable ipv6
421 mime "application/rtf" "rtf"
423 server "example.com" {
424 cert "/path/to/cert.pem"
425 key "/path/to/key.pem"
426 root "/var/gemini/example.com"
429 server "it.example.com" {
430 cert "/path/to/cert.pem"
431 key "/path/to/key.pem"
432 root "/var/gemini/it.example.com"
438 Yet another example, showing how to enable a
443 .Bd -literal -offset indent
447 server "example.com" {
448 cert "/path/to/cert.pem"
449 key "/path/to/key.pem"
450 root "/example.com" # in the /var/gemini chroot
452 location "/static/*" {
461 .Dq Flexible and Economical
462 UTF-8 decoder written by
463 .An Bjoern Hoehrmann .
468 program was written by
469 .An Omar Polo Aq Mt op@omarpolo.com .
473 The root directories of all virtual hosts are opened during the daemon
474 startup; this means that if a root directory gets deleted and then
477 won't be able to serve files inside that directory until a restart.
478 This restriction applies only to the root directories and not their content.
480 a %2F sequence is indistinguishable from a literal slash: this is not
483 a %00 sequence is treated as invalid character and thus rejected.
