1 f28d96d3 2021-01-25 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
3 3e4749f7 2020-10-02 op .\" Permission to use, copy, modify, and distribute this software for any
4 3e4749f7 2020-10-02 op .\" purpose with or without fee is hereby granted, provided that the above
5 3e4749f7 2020-10-02 op .\" copyright notice and this permission notice appear in all copies.
7 3e4749f7 2020-10-02 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 3e4749f7 2020-10-02 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 3e4749f7 2020-10-02 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 3e4749f7 2020-10-02 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 3e4749f7 2020-10-02 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 3e4749f7 2020-10-02 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 3e4749f7 2020-10-02 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 f28d96d3 2021-01-25 op .Dd $Mdocdate: January 25 2021$
19 fab952e1 2020-10-03 op .Nd dead simple zero configuration gemini server
24 15902770 2021-01-15 op .Op Fl c Ar config
27 f28d96d3 2021-01-25 op .Op Fl d Pa certs-dir
28 f28d96d3 2021-01-25 op .Op Fl H Ar hostname
29 721e2325 2020-11-18 op .Op Fl p Ar port
30 f28d96d3 2021-01-25 op .Op Fl x Pa cgi
33 3e4749f7 2020-10-02 op .Sh DESCRIPTION
35 b9220ca4 2021-01-11 op is a simple and minimal gemini server that can serve static files and
36 b9220ca4 2021-01-11 op execute CGI scripts.
37 eb699783 2021-01-18 op It can run without a configuration file with a limited set of features
39 eb699783 2021-01-18 op If a configuration file is given, no other flags shall be given,
46 df6ca41d 2020-12-25 op fully supports IRIs (Internationalized Resource Identifiers, see
49 eb699783 2021-01-18 op The options are as follows:
50 f28d96d3 2021-01-25 op .Bl -tag -width 14m
51 eb699783 2021-01-18 op .It Fl c Pa config
52 f28d96d3 2021-01-25 op Specify the configuration file.
54 46af8c6c 2021-01-27 op Stays and logs on the foreground.
56 eb699783 2021-01-18 op Check that the configuration is valid, but don't start the server.
59 eb699783 2021-01-18 op If no configuration file is given,
61 f28d96d3 2021-01-25 op will look for the following options
62 f28d96d3 2021-01-25 op .Bl -tag -width 14m
65 f28d96d3 2021-01-25 op .It Fl d Pa certs-path
66 f28d96d3 2021-01-25 op Directory where certificates for the config-less mode are stored.
68 f28d96d3 2021-01-25 op .Pa $XDG_DATA_HOME/gmid ,
70 f28d96d3 2021-01-25 op .Pa ~/.local/share/gmid .
71 71cf3975 2021-01-25 op .It Fl H Ar hostname
72 f28d96d3 2021-01-25 op The hostname, by default
73 f28d96d3 2021-01-25 op .Ar localhost .
74 f28d96d3 2021-01-25 op Certificates for the given
76 f28d96d3 2021-01-25 op are searched inside the
78 f28d96d3 2021-01-25 op directory given with the
81 f28d96d3 2021-01-25 op The have the form
82 f28d96d3 2021-01-25 op .Pa hostname.cert.pem
84 f28d96d3 2021-01-25 op .Pa hostname.key.pem .
85 f28d96d3 2021-01-25 op If a certificate and key doesn't exists for a given hostname they
86 f28d96d3 2021-01-25 op would be automatically generated.
88 fab952e1 2020-10-03 op Print the usage and exit.
89 721e2325 2020-11-18 op .It Fl p Ar port
90 eb699783 2021-01-18 op The port to listen on, by default 1965.
92 8904fa0e 2021-01-27 op Increase the verbosity of the logs.
93 f28d96d3 2021-01-25 op .It Fl x Pa path
94 eb699783 2021-01-18 op Enable execution of CGI scripts.
95 eb699783 2021-01-18 op See the description of the
98 eb699783 2021-01-18 op option in the section
100 eb699783 2021-01-18 op below to learn how
102 eb699783 2021-01-18 op is processed.
103 eb699783 2021-01-18 op Cannot be provided more than once.
105 f28d96d3 2021-01-25 op The root directory to serve.
106 f28d96d3 2021-01-25 op By default the current working directory is assumed.
108 eb699783 2021-01-18 op .Sh CONFIGURATION FILE
109 eb699783 2021-01-18 op The configuration file is divided into two sections:
110 eb699783 2021-01-18 op .Bl -tag -width xxxx
111 eb699783 2021-01-18 op .It Sy Global Options
112 eb699783 2021-01-18 op Global settings for
114 eb699783 2021-01-18 op .It Sy Servers
115 f28d96d3 2021-01-25 op Virtual hosts definition.
118 eb699783 2021-01-18 op Within the sections, empty lines are ignored and comments can be put
119 eb699783 2021-01-18 op anywhere in the file using a hash mark
121 eb699783 2021-01-18 op and extend to the end of the current line.
122 eb699783 2021-01-18 op A boolean is either the symbol
126 f28d96d3 2021-01-25 op A string is a sequence of characters wrapped in double quotes,
127 f28d96d3 2021-01-25 op .Dq like this .
128 eb699783 2021-01-18 op .Ss Global Options
129 eb699783 2021-01-18 op .Bl -tag -width 12m
130 eb699783 2021-01-18 op .It Ic ipv6 Ar bool
131 eb699783 2021-01-18 op Enable or disable IPv6 support.
132 eb699783 2021-01-18 op By default is off.
133 eb699783 2021-01-18 op .It Ic port Ar portno
134 eb699783 2021-01-18 op The port to listen on.
135 eb699783 2021-01-18 op By default is 1965.
136 eb699783 2021-01-18 op .It Ic protocols Ar string
137 eb699783 2021-01-18 op Specify the TLS protocols to enable.
139 eb699783 2021-01-18 op .Xr tls_config_parse_protocols 3
140 eb699783 2021-01-18 op for the valid protocol string values.
141 eb699783 2021-01-18 op By default, both TLSv1.3 and TLSv1.2 are used.
144 eb699783 2021-01-18 op to enable only TLSv1.3.
145 eb699783 2021-01-18 op .It Ic mime Ar mime-type Ar file-extension
146 eb699783 2021-01-18 op Add a mapping for the given
147 eb699783 2021-01-18 op .Ar file-extension
149 eb699783 2021-01-18 op .Ar mime-type .
150 eb699783 2021-01-18 op Both argument are strings.
151 ae08ec7d 2021-01-25 op .It Ic chroot Pa path
153 ae08ec7d 2021-01-25 op the process to the given
155 ae08ec7d 2021-01-25 op The daemon has to be run with root privileges and thus the option
157 ae08ec7d 2021-01-25 op needs to be provided, so
159 ae08ec7d 2021-01-25 op can drop the privileges.
160 ae08ec7d 2021-01-25 op Note that they are dropped after loading the TLS keys, so it's
161 ae08ec7d 2021-01-25 op recommended to put those outside the chroot.
162 ae08ec7d 2021-01-25 op Future version of
164 ae08ec7d 2021-01-25 op may require this.
165 ae08ec7d 2021-01-25 op .It Ic user Ar string
166 ae08ec7d 2021-01-25 op Run the daemon as the given user.
169 eb699783 2021-01-18 op Every virtual host is defined by a
172 eb699783 2021-01-18 op .Bl -tag -width Ds
173 eb699783 2021-01-18 op .It Ic server Ar hostname Brq ...
174 75fbb178 2021-01-28 op Match the server name using shell globbing rules.
175 75fbb178 2021-01-28 op This can be an explicit name,
176 de27389e 2021-01-21 op .Ar www.example.com ,
177 de27389e 2021-01-21 op or a name including a wildcards,
178 de27389e 2021-01-21 op .Ar *.example.com .
181 eb699783 2021-01-18 op Followed by a block of options that is enclosed in curly brackets:
182 eb699783 2021-01-18 op .Bl -tag -width Ds
183 eb699783 2021-01-18 op .It Ic cert Pa file
184 eb699783 2021-01-18 op Path to the certificate to use for this server.
187 eb699783 2021-01-18 op should contain a PEM encoded certificate.
188 eb699783 2021-01-18 op This option is mandatory.
189 eb699783 2021-01-18 op .It Ic key Pa file
190 eb699783 2021-01-18 op Specify the private key to use for this server.
193 eb699783 2021-01-18 op should contain a PEM encoded private key.
194 eb699783 2021-01-18 op This option is mandatory.
195 eb699783 2021-01-18 op .It Ic root Pa directory
196 eb699783 2021-01-18 op Specify the root directory for this server.
197 eb699783 2021-01-18 op This option is mandatory.
198 f28d96d3 2021-01-25 op It's relative to the chroot, if enabled.
199 eb699783 2021-01-18 op .It Ic cgi Pa path
200 eb699783 2021-01-18 op Enable the execution of CGI scripts if
202 eb699783 2021-01-18 op is a prefix of the user request string.
203 eb699783 2021-01-18 op An empty path "" will effectively enable the execution of any file
204 eb699783 2021-01-18 op with the executable bit set inside the root directory.
205 6119e13e 2021-01-19 op .It Ic default type Ar string
206 6119e13e 2021-01-19 op Set the default media type that is used if the media type for a
207 6119e13e 2021-01-19 op specified extension is not found.
208 6119e13e 2021-01-19 op If not specified, the
209 6119e13e 2021-01-19 op .Ic default type
211 6119e13e 2021-01-19 op .Dq application/octet-stream .
212 05c23a54 2021-01-19 op .It Ic lang Ar string
213 05c23a54 2021-01-19 op Specify the language tag for the text/gemini content served.
214 05c23a54 2021-01-19 op If not specified, no
216 05c23a54 2021-01-19 op parameter will be added in the response.
217 e7a2a99b 2021-01-24 op .It Ic index Ar string
218 e7a2a99b 2021-01-24 op Set the directory index file.
219 e7a2a99b 2021-01-24 op If not specified, it defaults to
220 f28d96d3 2021-01-25 op .Pa index.gmi .
221 252908e6 2021-01-24 op .It Ic auto Ic index Ar bool
222 252908e6 2021-01-24 op If no index file is found, automatically generate a directory listing.
223 252908e6 2021-01-24 op It's disabled by default.
224 c8b74339 2021-01-24 op .It Ic location Pa path Brq ...
225 c8b74339 2021-01-24 op Specify server configuration rules for a specific location.
228 c8b74339 2021-01-24 op argument will be matched against the request path with shell globbing
230 c8b74339 2021-01-24 op In case of multiple location statements in the same context, the last
231 c8b74339 2021-01-24 op matching location will be put into effect.
232 c8b74339 2021-01-24 op Therefore is advisable to match for a generic paths first and for more
233 c8b74339 2021-01-24 op specific ones later on.
236 c8b74339 2021-01-24 op section may include most of the server configuration rules
238 c8b74339 2021-01-24 op .Ic cert , Ic key , Ic root , Ic location No and Ic CGI .
241 0ed56567 2020-11-06 op When CGI scripts are enabled for a directory, a request for an
242 0ed56567 2020-11-06 op executable file will execute it and fed its output to the client.
244 a7b9bb4d 2021-01-24 op The CGI scripts are executed in the root directory of the virtual
245 a7b9bb4d 2021-01-24 op host, or in the served directory if run without config, and inherits
246 a7b9bb4d 2021-01-24 op the environment from
248 0ed56567 2020-11-06 op with these additional variables set:
249 a5d310bc 2020-11-10 op .Bl -tag -width 18m
250 28ec6178 2021-01-24 op .It Ev GATEWAY_INTERFACE
252 28ec6178 2021-01-24 op .It Ev SERVER_PROTOCOL
254 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
256 0ed56567 2020-11-06 op .It Ev SERVER_PORT
258 28ec6178 2021-01-24 op .It Ev SERVER_NAME
260 28ec6178 2021-01-24 op This variable is not available when operating without a configuration.
261 a5d310bc 2020-11-10 op .It Ev SCRIPT_NAME
262 28ec6178 2021-01-24 op The (public) path to the script, e.g.
263 28ec6178 2021-01-24 op .Pa "/cgi-bin/example.cgi"
264 a5d310bc 2020-11-10 op .It Ev SCRIPT_EXECUTABLE
265 a5d310bc 2020-11-10 op The full path to the executable.
266 a5d310bc 2020-11-10 op .It Ev REQUEST_URI
267 a5d310bc 2020-11-10 op The user request (without the query parameters.)
268 a5d310bc 2020-11-10 op .It Ev REQUEST_RELATIVE
269 a5d310bc 2020-11-10 op The request relative to the script.
270 0ed56567 2020-11-06 op .It Ev QUERY_STRING
271 a5d310bc 2020-11-10 op The query parameters.
272 a5d310bc 2020-11-10 op .It Ev REMOTE_HOST
273 a5d310bc 2020-11-10 op The remote IP address.
274 677afbd3 2020-12-02 op .It Ev REMOTE_ADDR
275 677afbd3 2020-12-02 op The remote IP address.
276 a5d310bc 2020-11-10 op .It Ev DOCUMENT_ROOT
277 a5d310bc 2020-11-10 op The root directory being served, the one provided with the
281 eb699783 2021-01-18 op or the root directory of the virtual host.
282 677afbd3 2020-12-02 op .It Ev AUTH_TYPE
283 28ec6178 2021-01-24 op The string "Certificate" if the client used a certificate, otherwise
285 677afbd3 2020-12-02 op .It Ev REMOTE_USER
286 677afbd3 2020-12-02 op The subject of the client certificate if provided, otherwise unset.
287 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_ISSUER
288 28ec6178 2021-01-24 op The is the issuer of the client certificate if provided, otherwise
290 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_HASH
291 677afbd3 2020-12-02 op The hash of the client certificate if provided, otherwise unset.
292 677afbd3 2020-12-02 op The format is "ALGO:HASH".
295 a5d310bc 2020-11-10 op Let's say you have a script in
296 a5d310bc 2020-11-10 op .Pa /cgi-bin/script
297 a5d310bc 2020-11-10 op and the user request is
298 a5d310bc 2020-11-10 op .Pa /cgi-bin/script/foo/bar?quux .
300 a5d310bc 2020-11-10 op .Ev SCRIPT_NAME
302 b9220ca4 2021-01-11 op .Pa cgi-bin/script ,
303 a5d310bc 2020-11-10 op .Ev SCRIPT_EXECUTABLE
305 a5d310bc 2020-11-10 op .Pa $DOCUMENT_ROOT/cgi-bin/script ,
306 a5d310bc 2020-11-10 op .Ev REQUEST_URI
308 b9220ca4 2021-01-11 op .Pa cgi-bin/script/foo/bar ,
309 a5d310bc 2020-11-10 op .Ev REQUEST_RELATIVE
313 a5d310bc 2020-11-10 op .Ev QUERY_STRING
317 75fbb178 2021-01-28 op To auto-detect the MIME type of the response
319 75fbb178 2021-01-28 op looks at the file extension and consults its internal table.
320 75fbb178 2021-01-28 op By default the following mappings are loaded, but they can be
321 75fbb178 2021-01-28 op overridden or extended using the
323 75fbb178 2021-01-28 op configuration option.
324 75fbb178 2021-01-28 op If no MIME is found, the value of
325 75fbb178 2021-01-28 op .Ic default type
326 75fbb178 2021-01-28 op matching the file
328 75fbb178 2021-01-28 op will be used, which is
329 75fbb178 2021-01-28 op .Dq application/octet-stream
332 75fbb178 2021-01-28 op .Bl -tag -offset indent -width 14m -compact
333 75fbb178 2021-01-28 op .It gemini, gmi
341 75fbb178 2021-01-28 op .It markdown, md
342 75fbb178 2021-01-28 op text/markdown
344 75fbb178 2021-01-28 op application/pdf
348 75fbb178 2021-01-28 op image/svg+xml
355 f28d96d3 2021-01-25 op Serve the current directory
356 6980aad6 2020-10-02 op .Bd -literal -offset indent
360 f28d96d3 2021-01-25 op To serve the directory
362 f28d96d3 2021-01-25 op and enable CGI scripts inside
363 f28d96d3 2021-01-25 op .Pa docs/cgi ,
365 0ed56567 2020-11-06 op .Bd -literal -offset indent
366 f28d96d3 2021-01-25 op $ mkdir docs/cgi
367 f28d96d3 2021-01-25 op $ cat <<EOF > cgi/hello
369 0ed56567 2020-11-06 op printf "20 text/plain\\r\\n"
370 f28d96d3 2021-01-25 op echo "hello world"
372 f28d96d3 2021-01-25 op $ chmod +x docs/cgi/hello
373 f28d96d3 2021-01-25 op $ gmid -x cgi docs
376 0ed56567 2020-11-06 op Note that the argument to the
381 f28d96d3 2021-01-25 op .Pa docs/cgi ,
382 a5d310bc 2020-11-10 op since it's relative to the document root.
384 eb699783 2021-01-18 op The following is an example of a possible configuration for a site
385 eb699783 2021-01-18 op that enables only TLSv1.3, adds a mime type for the file extension
386 eb699783 2021-01-18 op "rtf" and defines two virtual host:
387 eb699783 2021-01-18 op .Bd -literal -offset indent
388 eb699783 2021-01-18 op ipv6 on # enable ipv6
390 eb699783 2021-01-18 op protocols "tlsv1.3"
392 eb699783 2021-01-18 op mime "application/rtf" "rtf"
394 eb699783 2021-01-18 op server "example.com" {
395 eb699783 2021-01-18 op cert "/path/to/cert.pem"
396 eb699783 2021-01-18 op key "/path/to/key.pem"
397 eb699783 2021-01-18 op root "/var/gemini/example.com"
400 eb699783 2021-01-18 op server "it.example.com" {
401 eb699783 2021-01-18 op cert "/path/to/cert.pem"
402 eb699783 2021-01-18 op key "/path/to/key.pem"
403 eb699783 2021-01-18 op root "/var/gemini/it.example.com"
404 eb699783 2021-01-18 op cgi "/cgi-bin"
409 f28d96d3 2021-01-25 op Yet another example, showing how to enable a
414 f28d96d3 2021-01-25 op .Bd -literal -offset indent
415 f28d96d3 2021-01-25 op chroot "/var/gemini"
418 f28d96d3 2021-01-25 op server "example.com" {
419 f28d96d3 2021-01-25 op cert "/path/to/cert.pem"
420 f28d96d3 2021-01-25 op key "/path/to/key.pem"
421 f28d96d3 2021-01-25 op root "/var/gemini/example.com"
423 f28d96d3 2021-01-25 op location "/static/" {
424 f28d96d3 2021-01-25 op auto index on
425 f28d96d3 2021-01-25 op index "index.gemini"
429 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
432 eb699783 2021-01-18 op .Dq Flexible and Economical
433 eb699783 2021-01-18 op UTF-8 decoder written by
434 f28d96d3 2021-01-25 op .An Bjoern Hoehrmann .
438 eb699783 2021-01-18 op The root directories of all virtual hosts are opened during the daemon
439 eb699783 2021-01-18 op startup; this means that if a root directory gets deleted and then
442 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
443 eb699783 2021-01-18 op This restriction applies only to the root directories and not their content.
445 043acc97 2020-12-25 op a %2F sequence in the path part is indistinguishable from a literal
446 043acc97 2020-12-25 op slash: this is not RFC3986-compliant.
448 00781742 2020-12-25 op a %00 sequence either in the path or in the query part is treated as
449 00781742 2020-12-25 op invalid character and thus rejected.
