1 .\" Copyright (c) 2020 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: October 2 2020$
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,
44 fully supports IRIs (Internationalized Resource Identifiers, see
47 The options are as follows:
50 Specifies the configuration file.
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 option
62 The certificate to use.
64 The root directory to serve.
66 Stays and log in the foreground, do not daemonize the process.
68 Print the usage and exit.
70 The key for the certificate.
72 The port to listen on, by default 1965.
74 Enable execution of CGI scripts.
75 See the description of the
83 Cannot be provided more than once.
85 .Sh CONFIGURATION FILE
86 The configuration file is divided into two sections:
92 Virtual hosts definition
95 Within the sections, empty lines are ignored and comments can be put
96 anywhere in the file using a hash mark
98 and extend to the end of the current line.
99 A boolean is either the symbol
105 .It Ic daemon Ar bool
106 Enable or disables the daemon mode.
109 will log to syslog and fork in the background.
112 Enable or disable IPv6 support.
114 .It Ic port Ar portno
115 The port to listen on.
117 .It Ic protocols Ar string
118 Specify the TLS protocols to enable.
120 .Xr tls_config_parse_protocols 3
121 for the valid protocol string values.
122 By default, both TLSv1.3 and TLSv1.2 are used.
125 to enable only TLSv1.3.
126 .It Ic mime Ar mime-type Ar file-extension
127 Add a mapping for the given
131 Both argument are strings.
132 .It Ic chroot Pa path
134 the process to the given
136 The daemon has to be run with root privileges and thus the option
138 needs to be provided, so
140 can drop the privileges.
141 Note that they are dropped after loading the TLS keys, so it's
142 recommended to put those outside the chroot.
146 .It Ic user Ar string
147 Run the daemon as the given user.
150 Every virtual host is defined by a
154 .It Ic server Ar hostname Brq ...
155 Match the server name using shell globbing rules. This can be an explicit name,
156 .Ar www.example.com ,
157 or a name including a wildcards,
161 Followed by a block of options that is enclosed in curly brackets:
164 Path to the certificate to use for this server.
167 should contain a PEM encoded certificate.
168 This option is mandatory.
170 Specify the private key to use for this server.
173 should contain a PEM encoded private key.
174 This option is mandatory.
175 .It Ic root Pa directory
176 Specify the root directory for this server.
177 This option is mandatory.
179 Enable the execution of CGI scripts if
181 is a prefix of the user request string.
182 An empty path "" will effectively enable the execution of any file
183 with the executable bit set inside the root directory.
184 .It Ic default type Ar string
185 Set the default media type that is used if the media type for a
186 specified extension is not found.
187 If not specified, the
190 .Dq application/octet-stream .
191 .It Ic lang Ar string
192 Specify the language tag for the text/gemini content served.
195 parameter will be added in the response.
196 .It Ic index Ar string
197 Set the directory index file.
198 If not specified, it defaults to
200 .It Ic auto Ic index Ar bool
201 If no index file is found, automatically generate a directory listing.
202 It's disabled by default.
203 .It Ic location Pa path Brq ...
204 Specify server configuration rules for a specific location.
207 argument will be matched against the request path with shell globbing
209 In case of multiple location statements in the same context, the last
210 matching location will be put into effect.
211 Therefore is advisable to match for a generic paths first and for more
212 specific ones later on.
215 section may include most of the server configuration rules
217 .Ic cert , Ic key , Ic root , Ic location No and Ic CGI .
220 When CGI scripts are enabled for a directory, a request for an
221 executable file will execute it and fed its output to the client.
223 The CGI scripts are executed in the root directory of the virtual
224 host, or in the served directory if run without config, and inherits
227 with these additional variables set:
229 .It Ev GATEWAY_INTERFACE
231 .It Ev SERVER_PROTOCOL
233 .It Ev SERVER_SOFTWARE
239 This variable is not available when operating without a configuration.
241 The (public) path to the script, e.g.
242 .Pa "/cgi-bin/example.cgi"
243 .It Ev SCRIPT_EXECUTABLE
244 The full path to the executable.
246 The user request (without the query parameters.)
247 .It Ev REQUEST_RELATIVE
248 The request relative to the script.
250 The query parameters.
252 The remote IP address.
254 The remote IP address.
256 The root directory being served, the one provided with the
260 or the root directory of the virtual host.
262 The string "Certificate" if the client used a certificate, otherwise
265 The subject of the client certificate if provided, otherwise unset.
266 .It Ev TLS_CLIENT_ISSUER
267 The is the issuer of the client certificate if provided, otherwise
269 .It Ev TLS_CLIENT_HASH
270 The hash of the client certificate if provided, otherwise unset.
271 The format is "ALGO:HASH".
274 Let's say you have a script in
276 and the user request is
277 .Pa /cgi-bin/script/foo/bar?quux .
282 .Ev SCRIPT_EXECUTABLE
284 .Pa $DOCUMENT_ROOT/cgi-bin/script ,
287 .Pa cgi-bin/script/foo/bar ,
296 To quickly getting started
297 .Bd -literal -offset indent
298 $ # generate a cert and a key
299 $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
300 -out cert.pem -days 365 -nodes
302 $ cat <<EOF > docs/index.gmi
306 $ gmid -C cert.pem -K key.pem -d docs
309 Now you can visit gemini://localhost/ with your preferred gemini
312 To add some CGI scripts, assuming a setup similar to the previous
314 .Bd -literal -offset indent
316 $ cat <<EOF > docs/cgi-bin/hello-world
318 printf "20 text/plain\\r\\n"
321 $ gmid -C cert.pem -K key.pem -d docs -x cgi-bin
324 Note that the argument to the
330 since it's relative to the document root.
332 The following is an example of a possible configuration for a site
333 that enables only TLSv1.3, adds a mime type for the file extension
334 "rtf" and defines two virtual host:
335 .Bd -literal -offset indent
336 ipv6 on # enable ipv6
337 daemon on # enable daemon mode
341 mime "application/rtf" "rtf"
343 server "example.com" {
344 cert "/path/to/cert.pem"
345 key "/path/to/key.pem"
346 root "/var/gemini/example.com"
349 server "it.example.com" {
350 cert "/path/to/cert.pem"
351 key "/path/to/key.pem"
352 root "/var/gemini/it.example.com"
360 .Dq Flexible and Economical
361 UTF-8 decoder written by
367 The root directories of all virtual hosts are opened during the daemon
368 startup; this means that if a root directory gets deleted and then
371 won't be able to serve files inside that directory until a restart.
372 This restriction applies only to the root directories and not their content.
374 a %2F sequence in the path part is indistinguishable from a literal
375 slash: this is not RFC3986-compliant.
377 a %00 sequence either in the path or in the query part is treated as
378 invalid character and thus rejected.
