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 39a7b611 2021-01-30 op .Dd $Mdocdate: January 30 2021$
19 714685c1 2021-01-30 op .Nd simple and secure Gemini server
24 15902770 2021-01-15 op .Op Fl c Ar config
29 f28d96d3 2021-01-25 op .Op Fl d Pa certs-dir
30 f28d96d3 2021-01-25 op .Op Fl H Ar hostname
31 721e2325 2020-11-18 op .Op Fl p Ar port
32 f28d96d3 2021-01-25 op .Op Fl x Pa cgi
35 3e4749f7 2020-10-02 op .Sh DESCRIPTION
37 b9220ca4 2021-01-11 op is a simple and minimal gemini server that can serve static files and
38 b9220ca4 2021-01-11 op execute CGI scripts.
39 eb699783 2021-01-18 op It can run without a configuration file with a limited set of features
43 3007f565 2021-02-04 op rereads the configuration file when it receives
46 eb699783 2021-01-18 op The options are as follows:
47 f28d96d3 2021-01-25 op .Bl -tag -width 14m
48 eb699783 2021-01-18 op .It Fl c Pa config
49 f28d96d3 2021-01-25 op Specify the configuration file.
51 46af8c6c 2021-01-27 op Stays and logs on the foreground.
53 eb699783 2021-01-18 op Check that the configuration is valid, but don't start the server.
56 eb699783 2021-01-18 op If no configuration file is given,
58 f28d96d3 2021-01-25 op will look for the following options
59 f28d96d3 2021-01-25 op .Bl -tag -width 14m
62 f28d96d3 2021-01-25 op .It Fl d Pa certs-path
63 f28d96d3 2021-01-25 op Directory where certificates for the config-less mode are stored.
65 f28d96d3 2021-01-25 op .Pa $XDG_DATA_HOME/gmid ,
67 f28d96d3 2021-01-25 op .Pa ~/.local/share/gmid .
68 71cf3975 2021-01-25 op .It Fl H Ar hostname
69 f28d96d3 2021-01-25 op The hostname, by default
70 f28d96d3 2021-01-25 op .Ar localhost .
71 f28d96d3 2021-01-25 op Certificates for the given
73 f28d96d3 2021-01-25 op are searched inside the
75 f28d96d3 2021-01-25 op directory given with the
78 714685c1 2021-01-30 op They have the form
79 f28d96d3 2021-01-25 op .Pa hostname.cert.pem
81 f28d96d3 2021-01-25 op .Pa hostname.key.pem .
82 f28d96d3 2021-01-25 op If a certificate and key doesn't exists for a given hostname they
83 714685c1 2021-01-30 op will be automatically generated.
85 fab952e1 2020-10-03 op Print the usage and exit.
86 721e2325 2020-11-18 op .It Fl p Ar port
87 eb699783 2021-01-18 op The port to listen on, by default 1965.
89 8904fa0e 2021-01-27 op Increase the verbosity of the logs.
90 f28d96d3 2021-01-25 op .It Fl x Pa path
91 eb699783 2021-01-18 op Enable execution of CGI scripts.
92 eb699783 2021-01-18 op See the description of the
94 eb699783 2021-01-18 op option in the section
96 eb699783 2021-01-18 op below to learn how
99 eb699783 2021-01-18 op Cannot be provided more than once.
101 f28d96d3 2021-01-25 op The root directory to serve.
102 f28d96d3 2021-01-25 op By default the current working directory is assumed.
104 eb699783 2021-01-18 op .Sh CONFIGURATION FILE
105 eb699783 2021-01-18 op The configuration file is divided into two sections:
106 eb699783 2021-01-18 op .Bl -tag -width xxxx
107 eb699783 2021-01-18 op .It Sy Global Options
108 eb699783 2021-01-18 op Global settings for
110 eb699783 2021-01-18 op .It Sy Servers
111 f28d96d3 2021-01-25 op Virtual hosts definition.
114 eb699783 2021-01-18 op Within the sections, empty lines are ignored and comments can be put
115 eb699783 2021-01-18 op anywhere in the file using a hash mark
117 eb699783 2021-01-18 op and extend to the end of the current line.
118 eb699783 2021-01-18 op A boolean is either the symbol
122 f28d96d3 2021-01-25 op A string is a sequence of characters wrapped in double quotes,
123 f28d96d3 2021-01-25 op .Dq like this .
124 eb699783 2021-01-18 op .Ss Global Options
125 eb699783 2021-01-18 op .Bl -tag -width 12m
126 ae08ec7d 2021-01-25 op .It Ic chroot Pa path
128 ae08ec7d 2021-01-25 op the process to the given
130 ae08ec7d 2021-01-25 op The daemon has to be run with root privileges and thus the option
132 714685c1 2021-01-30 op needs to be provided, so privileges can be dropped.
135 714685c1 2021-01-30 op will enter the chroot after loading the TLS keys, but before opening
136 714685c1 2021-01-30 op the virtual host root directories.
137 714685c1 2021-01-30 op It's recommended to keep the TLS keys outside the chroot.
138 ae08ec7d 2021-01-25 op Future version of
140 ae08ec7d 2021-01-25 op may require this.
141 2b92a447 2021-02-06 op .It Ic ipv6 Ar bool
142 2b92a447 2021-02-06 op Enable or disable IPv6 support.
143 2b92a447 2021-02-06 op By default is off.
144 2b92a447 2021-02-06 op .It Ic mime Ar mime-type Ar file-extension
145 2b92a447 2021-02-06 op Add a mapping for the given
146 2b92a447 2021-02-06 op .Ar file-extension
148 2b92a447 2021-02-06 op .Ar mime-type .
149 2b92a447 2021-02-06 op Both argument are strings.
150 2b92a447 2021-02-06 op .It Ic port Ar portno
151 2b92a447 2021-02-06 op The port to listen on.
152 2b92a447 2021-02-06 op By default is 1965.
153 2b92a447 2021-02-06 op .It Ic protocols Ar string
154 2b92a447 2021-02-06 op Specify the TLS protocols to enable.
156 2b92a447 2021-02-06 op .Xr tls_config_parse_protocols 3
157 2b92a447 2021-02-06 op for the valid protocol string values.
158 2b92a447 2021-02-06 op By default, both TLSv1.3 and TLSv1.2 are enabled.
161 2b92a447 2021-02-06 op to enable only TLSv1.3.
162 ae08ec7d 2021-01-25 op .It Ic user Ar string
163 ae08ec7d 2021-01-25 op Run the daemon as the given user.
166 eb699783 2021-01-18 op Every virtual host is defined by a
169 eb699783 2021-01-18 op .Bl -tag -width Ds
170 eb699783 2021-01-18 op .It Ic server Ar hostname Brq ...
171 75fbb178 2021-01-28 op Match the server name using shell globbing rules.
172 75fbb178 2021-01-28 op This can be an explicit name,
173 de27389e 2021-01-21 op .Ar www.example.com ,
174 de27389e 2021-01-21 op or a name including a wildcards,
175 de27389e 2021-01-21 op .Ar *.example.com .
178 eb699783 2021-01-18 op Followed by a block of options that is enclosed in curly brackets:
179 eb699783 2021-01-18 op .Bl -tag -width Ds
180 2b92a447 2021-02-06 op .It Ic auto Ic index Ar bool
181 2b92a447 2021-02-06 op If no index file is found, automatically generate a directory listing.
182 2b92a447 2021-02-06 op It's disabled by default.
183 2b92a447 2021-02-06 op .It Ic block Op Ic return Ar code Op Ar meta
184 2b92a447 2021-02-06 op Send a reply and close the connection;
190 2b92a447 2021-02-06 op .Dq temporary failure
194 2b92a447 2021-02-06 op is in the 3x range, then
196 2b92a447 2021-02-06 op must be provided.
199 2b92a447 2021-02-06 op the following special sequences are replaced:
200 2b92a447 2021-02-06 op .Bl -tag -compact
202 2b92a447 2021-02-06 op is replaced with a single
205 2b92a447 2021-02-06 op is replaced with the request path.
207 2b92a447 2021-02-06 op is replaced with the query string of the request.
209 2b92a447 2021-02-06 op is replaced with the server port.
211 2b92a447 2021-02-06 op is replaced with the server name.
213 eb699783 2021-01-18 op .It Ic cert Pa file
214 eb699783 2021-01-18 op Path to the certificate to use for this server.
217 eb699783 2021-01-18 op should contain a PEM encoded certificate.
218 eb699783 2021-01-18 op This option is mandatory.
219 eb699783 2021-01-18 op .It Ic cgi Pa path
220 87f2b68b 2021-02-02 op Execute CGI scripts that matches
222 87f2b68b 2021-02-02 op using shell globbing rules.
223 6119e13e 2021-01-19 op .It Ic default type Ar string
224 6119e13e 2021-01-19 op Set the default media type that is used if the media type for a
225 6119e13e 2021-01-19 op specified extension is not found.
226 6119e13e 2021-01-19 op If not specified, the
227 6119e13e 2021-01-19 op .Ic default type
229 6119e13e 2021-01-19 op .Dq application/octet-stream .
230 2b92a447 2021-02-06 op .It Ic entrypoint Pa path
231 2b92a447 2021-02-06 op Make the CGI script at
233 2b92a447 2021-02-06 op .Pq relative to the Ic root No directory
234 2b92a447 2021-02-06 op handle all the requests for the current virtual host
235 2b92a447 2021-02-06 op .It Ic index Ar string
236 2b92a447 2021-02-06 op Set the directory index file.
237 2b92a447 2021-02-06 op If not specified, it defaults to
238 2b92a447 2021-02-06 op .Pa index.gmi .
239 2b92a447 2021-02-06 op .It Ic key Pa file
240 2b92a447 2021-02-06 op Specify the private key to use for this server.
243 2b92a447 2021-02-06 op should contain a PEM encoded private key.
244 2b92a447 2021-02-06 op This option is mandatory.
245 05c23a54 2021-01-19 op .It Ic lang Ar string
246 05c23a54 2021-01-19 op Specify the language tag for the text/gemini content served.
247 05c23a54 2021-01-19 op If not specified, no
249 05c23a54 2021-01-19 op parameter will be added in the response.
250 c8b74339 2021-01-24 op .It Ic location Pa path Brq ...
251 c8b74339 2021-01-24 op Specify server configuration rules for a specific location.
254 c8b74339 2021-01-24 op argument will be matched against the request path with shell globbing
256 6016a593 2021-01-30 op In case of multiple location statements in the same context, the first
257 6016a593 2021-01-30 op matching location will be put into effect and the later ones ignored.
258 6016a593 2021-01-30 op Therefore is advisable to match for more specific paths first and for
259 6016a593 2021-01-30 op generic ones later on.
262 c8b74339 2021-01-24 op section may include most of the server configuration rules
264 2b92a447 2021-02-06 op .Ic cert , Ic key , Ic root , Ic location ,
265 e3ddf390 2021-02-06 op .Ic entrypoint No and Ic cgi .
266 2b92a447 2021-02-06 op .It Ic root Pa directory
267 2b92a447 2021-02-06 op Specify the root directory for this server.
268 2b92a447 2021-02-06 op This option is mandatory.
269 2b92a447 2021-02-06 op It's relative to the chroot, if enabled.
270 6abda252 2021-02-06 op .It Ic strip Ar number
273 6abda252 2021-02-06 op components from the beginning of the path.
274 6abda252 2021-02-06 op It's only considered for the
276 2b92a447 2021-02-06 op parameter in the scope of a
277 6abda252 2021-02-06 op .Ic block return .
280 87f2b68b 2021-02-02 op When a request for an executable file matches the
282 87f2b68b 2021-02-02 op rule, that file will be execute and its output fed to the client.
284 ee655e64 2021-02-01 op The CGI scripts are executed in the directory they reside and inherit
285 a7b9bb4d 2021-01-24 op the environment from
287 0ed56567 2020-11-06 op with these additional variables set:
288 ee655e64 2021-02-01 op .Bl -tag -width 24m
289 28ec6178 2021-01-24 op .It Ev GATEWAY_INTERFACE
291 ee655e64 2021-02-01 op .It Ev GEMINI_DOCUMENT_ROOT
292 ee655e64 2021-02-01 op The root directory of the virtual host.
293 ee655e64 2021-02-01 op .It Ev GEMINI_SCRIPT_FILENAME
294 ee655e64 2021-02-01 op Full path to the CGI script being executed.
295 ee655e64 2021-02-01 op .It Ev GEMINI_URL
296 ee655e64 2021-02-01 op The full IRI of the request.
297 ee655e64 2021-02-01 op .It Ev GEMINI_URL_PATH
298 ee655e64 2021-02-01 op The path of the request.
299 ee655e64 2021-02-01 op .It Ev PATH_INFO
300 ee655e64 2021-02-01 op The portion of the requested path that is derived from the the IRI
301 ee655e64 2021-02-01 op path hierarchy following the part that identifies the script itself.
302 ee655e64 2021-02-01 op Can be unset.
303 ee655e64 2021-02-01 op .It Ev PATH_TRANSLATED
304 ee655e64 2021-02-01 op Present if and only if
305 ee655e64 2021-02-01 op .Ev PATH_INFO
307 ee655e64 2021-02-01 op It represent the translation of the
308 ee655e64 2021-02-01 op .Ev PATH_INFO .
310 ee655e64 2021-02-01 op builds this by appending the
311 ee655e64 2021-02-01 op .Ev PATH_INFO
312 ee655e64 2021-02-01 op to the virtual host directory root.
313 ee655e64 2021-02-01 op .It Ev QUERY_STRING
314 ee655e64 2021-02-01 op The decoded query string.
315 ee655e64 2021-02-01 op .It Ev REMOTE_ADDR , Ev REMOTE_HOST
316 ee655e64 2021-02-01 op Textual representation of the client IP.
317 ee655e64 2021-02-01 op .It Ev REQUEST_METHOD
318 ee655e64 2021-02-01 op This is present only for RFC3875 (CGI) compliance.
319 ee655e64 2021-02-01 op It's always set to the empty string.
320 ee655e64 2021-02-01 op .It Ev SCRIPT_NAME
321 ee655e64 2021-02-01 op The part of the
322 ee655e64 2021-02-01 op .Ev GEMINI_URL_PATH
323 ee655e64 2021-02-01 op that identifies the current CGI script.
324 ee655e64 2021-02-01 op .It Ev SERVER_NAME
325 ee655e64 2021-02-01 op The name of the server
326 ee655e64 2021-02-01 op .It Ev SERVER_PORT
327 ee655e64 2021-02-01 op The port the server is listening on.
328 28ec6178 2021-01-24 op .It Ev SERVER_PROTOCOL
330 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
331 ee655e64 2021-02-01 op The name and version of the server, i.e.
333 677afbd3 2020-12-02 op .It Ev AUTH_TYPE
334 28ec6178 2021-01-24 op The string "Certificate" if the client used a certificate, otherwise
336 677afbd3 2020-12-02 op .It Ev REMOTE_USER
337 677afbd3 2020-12-02 op The subject of the client certificate if provided, otherwise unset.
338 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_ISSUER
339 28ec6178 2021-01-24 op The is the issuer of the client certificate if provided, otherwise
341 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_HASH
342 677afbd3 2020-12-02 op The hash of the client certificate if provided, otherwise unset.
343 ee655e64 2021-02-01 op The format is
344 ee655e64 2021-02-01 op .Dq ALGO:HASH .
348 75fbb178 2021-01-28 op To auto-detect the MIME type of the response
350 75fbb178 2021-01-28 op looks at the file extension and consults its internal table.
351 75fbb178 2021-01-28 op By default the following mappings are loaded, but they can be
352 75fbb178 2021-01-28 op overridden or extended using the
354 75fbb178 2021-01-28 op configuration option.
355 75fbb178 2021-01-28 op If no MIME is found, the value of
356 75fbb178 2021-01-28 op .Ic default type
357 75fbb178 2021-01-28 op matching the file
359 75fbb178 2021-01-28 op will be used, which is
360 75fbb178 2021-01-28 op .Dq application/octet-stream
363 75fbb178 2021-01-28 op .Bl -tag -offset indent -width 14m -compact
364 75fbb178 2021-01-28 op .It gemini, gmi
372 75fbb178 2021-01-28 op .It markdown, md
373 75fbb178 2021-01-28 op text/markdown
375 75fbb178 2021-01-28 op application/pdf
379 75fbb178 2021-01-28 op image/svg+xml
386 f28d96d3 2021-01-25 op Serve the current directory
387 6980aad6 2020-10-02 op .Bd -literal -offset indent
391 f28d96d3 2021-01-25 op To serve the directory
393 f28d96d3 2021-01-25 op and enable CGI scripts inside
394 f28d96d3 2021-01-25 op .Pa docs/cgi ,
396 0ed56567 2020-11-06 op .Bd -literal -offset indent
397 f28d96d3 2021-01-25 op $ mkdir docs/cgi
398 f28d96d3 2021-01-25 op $ cat <<EOF > cgi/hello
400 0ed56567 2020-11-06 op printf "20 text/plain\\r\\n"
401 f28d96d3 2021-01-25 op echo "hello world"
403 f28d96d3 2021-01-25 op $ chmod +x docs/cgi/hello
404 f28d96d3 2021-01-25 op $ gmid -x cgi docs
407 eb699783 2021-01-18 op The following is an example of a possible configuration for a site
408 eb699783 2021-01-18 op that enables only TLSv1.3, adds a mime type for the file extension
409 eb699783 2021-01-18 op "rtf" and defines two virtual host:
410 eb699783 2021-01-18 op .Bd -literal -offset indent
411 eb699783 2021-01-18 op ipv6 on # enable ipv6
413 eb699783 2021-01-18 op protocols "tlsv1.3"
415 eb699783 2021-01-18 op mime "application/rtf" "rtf"
417 eb699783 2021-01-18 op server "example.com" {
418 eb699783 2021-01-18 op cert "/path/to/cert.pem"
419 eb699783 2021-01-18 op key "/path/to/key.pem"
420 eb699783 2021-01-18 op root "/var/gemini/example.com"
423 eb699783 2021-01-18 op server "it.example.com" {
424 eb699783 2021-01-18 op cert "/path/to/cert.pem"
425 eb699783 2021-01-18 op key "/path/to/key.pem"
426 eb699783 2021-01-18 op root "/var/gemini/it.example.com"
427 87f2b68b 2021-02-02 op cgi "/cgi-bin/*"
432 f28d96d3 2021-01-25 op Yet another example, showing how to enable a
437 f28d96d3 2021-01-25 op .Bd -literal -offset indent
438 f28d96d3 2021-01-25 op chroot "/var/gemini"
441 f28d96d3 2021-01-25 op server "example.com" {
442 f28d96d3 2021-01-25 op cert "/path/to/cert.pem"
443 f28d96d3 2021-01-25 op key "/path/to/key.pem"
444 714685c1 2021-01-30 op root "/example.com" # in the /var/gemini chroot
446 4ee08bd1 2021-02-03 op location "/static/*" {
447 f28d96d3 2021-01-25 op auto index on
448 f28d96d3 2021-01-25 op index "index.gemini"
452 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
455 eb699783 2021-01-18 op .Dq Flexible and Economical
456 eb699783 2021-01-18 op UTF-8 decoder written by
457 f28d96d3 2021-01-25 op .An Bjoern Hoehrmann .
462 714685c1 2021-01-30 op program was written by
463 714685c1 2021-01-30 op .An Omar Polo Aq Mt op@omarpolo.com .
467 eb699783 2021-01-18 op The root directories of all virtual hosts are opened during the daemon
468 eb699783 2021-01-18 op startup; this means that if a root directory gets deleted and then
471 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
472 eb699783 2021-01-18 op This restriction applies only to the root directories and not their content.
474 714685c1 2021-01-30 op a %2F sequence is indistinguishable from a literal slash: this is not
475 714685c1 2021-01-30 op RFC3986-compliant.
477 714685c1 2021-01-30 op a %00 sequence is treated as invalid character and thus rejected.