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.
134 Every virtual host is defined by a
138 .It Ic server Ar hostname Brq ...
139 Match the server name using shell globbing rules. This can be an explicit name,
140 .Ar www.example.com ,
141 or a name including a wildcards,
145 Followed by a block of options that is enclosed in curly brackets:
148 Path to the certificate to use for this server.
151 should contain a PEM encoded certificate.
152 This option is mandatory.
154 Specify the private key to use for this server.
157 should contain a PEM encoded private key.
158 This option is mandatory.
159 .It Ic root Pa directory
160 Specify the root directory for this server.
161 This option is mandatory.
163 Enable the execution of CGI scripts if
165 is a prefix of the user request string.
166 An empty path "" will effectively enable the execution of any file
167 with the executable bit set inside the root directory.
168 .It Ic default type Ar string
169 Set the default media type that is used if the media type for a
170 specified extension is not found.
171 If not specified, the
174 .Dq application/octet-stream .
175 .It Ic lang Ar string
176 Specify the language tag for the text/gemini content served.
179 parameter will be added in the response.
180 .It Ic index Ar string
181 Set the directory index file.
182 If not specified, it defaults to
184 .It Ic auto Ic index Ar bool
185 If no index file is found, automatically generate a directory listing.
186 It's disabled by default.
187 .It Ic location Pa path Brq ...
188 Specify server configuration rules for a specific location.
191 argument will be matched against the request path with shell globbing
193 In case of multiple location statements in the same context, the last
194 matching location will be put into effect.
195 Therefore is advisable to match for a generic paths first and for more
196 specific ones later on.
199 section may include most of the server configuration rules
201 .Ic cert , Ic key , Ic root , Ic location No and Ic CGI .
204 When CGI scripts are enabled for a directory, a request for an
205 executable file will execute it and fed its output to the client.
207 The CGI scripts are executed in the root directory of the virtual
208 host, or in the served directory if run without config, and inherits
211 with these additional variables set:
213 .It Ev GATEWAY_INTERFACE
215 .It Ev SERVER_PROTOCOL
217 .It Ev SERVER_SOFTWARE
223 This variable is not available when operating without a configuration.
225 The (public) path to the script, e.g.
226 .Pa "/cgi-bin/example.cgi"
227 .It Ev SCRIPT_EXECUTABLE
228 The full path to the executable.
230 The user request (without the query parameters.)
231 .It Ev REQUEST_RELATIVE
232 The request relative to the script.
234 The query parameters.
236 The remote IP address.
238 The remote IP address.
240 The root directory being served, the one provided with the
244 or the root directory of the virtual host.
246 The string "Certificate" if the client used a certificate, otherwise
249 The subject of the client certificate if provided, otherwise unset.
250 .It Ev TLS_CLIENT_ISSUER
251 The is the issuer of the client certificate if provided, otherwise
253 .It Ev TLS_CLIENT_HASH
254 The hash of the client certificate if provided, otherwise unset.
255 The format is "ALGO:HASH".
258 Let's say you have a script in
260 and the user request is
261 .Pa /cgi-bin/script/foo/bar?quux .
266 .Ev SCRIPT_EXECUTABLE
268 .Pa $DOCUMENT_ROOT/cgi-bin/script ,
271 .Pa cgi-bin/script/foo/bar ,
280 To quickly getting started
281 .Bd -literal -offset indent
282 $ # generate a cert and a key
283 $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
284 -out cert.pem -days 365 -nodes
286 $ cat <<EOF > docs/index.gmi
290 $ gmid -C cert.pem -K key.pem -d docs
293 Now you can visit gemini://localhost/ with your preferred gemini
296 To add some CGI scripts, assuming a setup similar to the previous
298 .Bd -literal -offset indent
300 $ cat <<EOF > docs/cgi-bin/hello-world
302 printf "20 text/plain\\r\\n"
305 $ gmid -C cert.pem -K key.pem -d docs -x cgi-bin
308 Note that the argument to the
314 since it's relative to the document root.
316 The following is an example of a possible configuration for a site
317 that enables only TLSv1.3, adds a mime type for the file extension
318 "rtf" and defines two virtual host:
319 .Bd -literal -offset indent
320 ipv6 on # enable ipv6
321 daemon on # enable daemon mode
325 mime "application/rtf" "rtf"
327 server "example.com" {
328 cert "/path/to/cert.pem"
329 key "/path/to/key.pem"
330 root "/var/gemini/example.com"
333 server "it.example.com" {
334 cert "/path/to/cert.pem"
335 key "/path/to/key.pem"
336 root "/var/gemini/it.example.com"
344 .Dq Flexible and Economical
345 UTF-8 decoder written by
351 The root directories of all virtual hosts are opened during the daemon
352 startup; this means that if a root directory gets deleted and then
355 won't be able to serve files inside that directory until a restart.
356 This restriction applies only to the root directories and not their content.
358 a %2F sequence in the path part is indistinguishable from a literal
359 slash: this is not RFC3986-compliant.
361 a %00 sequence either in the path or in the query part is treated as
362 invalid character and thus rejected.
