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 e58a447a 2021-07-29 op .Dd $Mdocdate: July 29 2021$
19 714685c1 2021-01-30 op .Nd simple and secure Gemini server
24 15902770 2021-01-15 op .Op Fl c Ar config
25 8b743dda 2021-06-29 op .Op Fl D Ar macro Ns = Ns Ar value
26 8e8b2e25 2021-04-28 op .Op Fl P Ar pidfile
31 f28d96d3 2021-01-25 op .Op Fl d Pa certs-dir
32 f28d96d3 2021-01-25 op .Op Fl H Ar hostname
33 721e2325 2020-11-18 op .Op Fl p Ar port
34 f28d96d3 2021-01-25 op .Op Fl x Pa cgi
37 3e4749f7 2020-10-02 op .Sh DESCRIPTION
39 8ff40039 2021-05-24 op is a simple and minimal gemini server that can serve static files,
40 8ff40039 2021-05-24 op execute CGI scripts and talk to FastCGI applications.
41 eb699783 2021-01-18 op It can run without a configuration file with a limited set of features
45 3007f565 2021-02-04 op rereads the configuration file when it receives
48 eb699783 2021-01-18 op The options are as follows:
49 f28d96d3 2021-01-25 op .Bl -tag -width 14m
50 eb699783 2021-01-18 op .It Fl c Pa config
51 f28d96d3 2021-01-25 op Specify the configuration file.
52 8b743dda 2021-06-29 op .It Fl D Ar macro Ns = Ns Ar value
57 8b743dda 2021-06-29 op on the command line.
58 8b743dda 2021-06-29 op Overrides the definition of
60 8b743dda 2021-06-29 op in the config file if present.
62 46af8c6c 2021-01-27 op Stays and logs on the foreground.
64 eb699783 2021-01-18 op Check that the configuration is valid, but don't start the server.
65 8e8b2e25 2021-04-28 op .It Fl P Pa pidfile
66 301e039d 2021-07-29 op Write daemon's pid to the given location.
68 2b520ad5 2021-07-09 op will also act as lock: if another process is holding a lock on that
71 2b520ad5 2021-07-09 op will refuse to start.
74 eb699783 2021-01-18 op If no configuration file is given,
76 f28d96d3 2021-01-25 op will look for the following options
77 f28d96d3 2021-01-25 op .Bl -tag -width 14m
80 f28d96d3 2021-01-25 op .It Fl d Pa certs-path
81 f28d96d3 2021-01-25 op Directory where certificates for the config-less mode are stored.
82 301e039d 2021-07-29 op By default it is
83 f28d96d3 2021-01-25 op .Pa $XDG_DATA_HOME/gmid ,
85 f28d96d3 2021-01-25 op .Pa ~/.local/share/gmid .
86 71cf3975 2021-01-25 op .It Fl H Ar hostname
92 f28d96d3 2021-01-25 op Certificates for the given
94 f28d96d3 2021-01-25 op are searched inside the
96 f28d96d3 2021-01-25 op directory given with the
99 714685c1 2021-01-30 op They have the form
100 f28d96d3 2021-01-25 op .Pa hostname.cert.pem
102 f28d96d3 2021-01-25 op .Pa hostname.key.pem .
103 301e039d 2021-07-29 op If a certificate or a key doesn't exist for a given hostname, they
104 301e039d 2021-07-29 op will be generated automatically.
105 ba65dcc8 2021-06-29 op .It Fl h , Fl -help
106 fab952e1 2020-10-03 op Print the usage and exit.
107 721e2325 2020-11-18 op .It Fl p Ar port
108 eb699783 2021-01-18 op The port to listen on, by default 1965.
109 ba65dcc8 2021-06-29 op .It Fl V , Fl -version
110 ba65dcc8 2021-06-29 op Print the version and exit.
112 3abf91b0 2021-02-07 op Verbose mode.
115 3abf91b0 2021-02-07 op options increase the verbosity.
116 f28d96d3 2021-01-25 op .It Fl x Pa path
117 301e039d 2021-07-29 op Enable execution of
120 eb699783 2021-01-18 op See the description of the
122 301e039d 2021-07-29 op option in the
124 301e039d 2021-07-29 op section below to learn how
126 eb699783 2021-01-18 op is processed.
127 eb699783 2021-01-18 op Cannot be provided more than once.
129 f28d96d3 2021-01-25 op The root directory to serve.
130 f28d96d3 2021-01-25 op By default the current working directory is assumed.
132 eb699783 2021-01-18 op .Sh CONFIGURATION FILE
133 8b743dda 2021-06-29 op The configuration file is divided into three sections:
134 eb699783 2021-01-18 op .Bl -tag -width xxxx
135 8b743dda 2021-06-29 op .It Sy Macros
136 8b743dda 2021-06-29 op User-defined variables may be defined and used later, simplifying the
137 8b743dda 2021-06-29 op configuration file.
138 eb699783 2021-01-18 op .It Sy Global Options
139 eb699783 2021-01-18 op Global settings for
141 eb699783 2021-01-18 op .It Sy Servers
142 f28d96d3 2021-01-25 op Virtual hosts definition.
145 eb699783 2021-01-18 op Within the sections, empty lines are ignored and comments can be put
146 eb699783 2021-01-18 op anywhere in the file using a hash mark
148 eb699783 2021-01-18 op and extend to the end of the current line.
149 eb699783 2021-01-18 op A boolean is either the symbol
153 f28d96d3 2021-01-25 op A string is a sequence of characters wrapped in double quotes,
154 f28d96d3 2021-01-25 op .Dq like this .
155 eaf7f776 2021-06-29 op Multiple strings one next to the other are joined into a single
157 eaf7f776 2021-06-29 op .Bd -literal -offset indent
158 eaf7f776 2021-06-29 op # equivalent to "temporary-failure"
159 eaf7f776 2021-06-29 op block return 40 "temporary" "-" "failure"
162 2b520ad5 2021-07-09 op Furthermore, quoting is necessary only when a string needs to contain
163 528f37cd 2021-07-09 op special characters
164 528f37cd 2021-07-09 op .Pq like spaces or punctuation ,
165 528f37cd 2021-07-09 op something that looks like a number or a reserved keyword.
166 2b520ad5 2021-07-09 op The last example could have been written also as:
167 2b520ad5 2021-07-09 op .Bd -literal -offset indent
168 2b520ad5 2021-07-09 op block return 40 temporary "-" failure
171 8b743dda 2021-06-29 op Strict ordering of the sections is not enforced, so that is possible
172 8b743dda 2021-06-29 op to mix macros, options and
175 8b743dda 2021-06-29 op However, defining all the
177 8b743dda 2021-06-29 op blocks after the macros and the global options is recommended.
179 528f37cd 2021-07-09 op Newlines are often optional, except around top-level instructions, and
182 528f37cd 2021-07-09 op can also be optionally used to separate options.
184 528f37cd 2021-07-09 op Additional configuration files can be included with the
186 528f37cd 2021-07-09 op keyword, for example:
187 528f37cd 2021-07-09 op .Bd -literal -offset indent
188 528f37cd 2021-07-09 op include "/etc/gmid.conf.local"
191 8b743dda 2021-06-29 op Macros can be defined that will later be expanded in context.
192 8b743dda 2021-06-29 op Macro names must start with a letter, digit or underscore and may
193 8b743dda 2021-06-29 op contain any of those characters.
194 4f9a2760 2021-07-02 op Macros names may not be reserved words.
195 bfb076ed 2021-06-29 op Macros are not expanded inside quotes.
197 528f37cd 2021-07-09 op Two kinds of macros are supported: variable-like and proper macros.
198 528f37cd 2021-07-09 op When a macro is invoked with a
200 528f37cd 2021-07-09 op before its name its expanded as a string, whereas when it's invoked
203 528f37cd 2021-07-09 op its expanded in-place.
206 8b743dda 2021-06-29 op .Bd -literal -offset indent
207 8b743dda 2021-06-29 op dir = "/var/gemini"
208 2d06ae62 2021-07-11 op certdir = "/etc/keys"
209 528f37cd 2021-07-09 op common = "lang it; auto index on"
211 8b743dda 2021-06-29 op server "foo" {
212 ad15003b 2021-07-11 op root $dir "/foo" # -> /var/gemini/foo
213 2d06ae62 2021-07-11 op cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
214 2d06ae62 2021-07-11 op key $certdir "/foo.pem" # -> /etc/keys/foo.pem
218 eb699783 2021-01-18 op .Ss Global Options
219 eb699783 2021-01-18 op .Bl -tag -width 12m
220 ae08ec7d 2021-01-25 op .It Ic chroot Pa path
222 ae08ec7d 2021-01-25 op the process to the given
224 ae08ec7d 2021-01-25 op The daemon has to be run with root privileges and thus the option
226 714685c1 2021-01-30 op needs to be provided, so privileges can be dropped.
229 714685c1 2021-01-30 op will enter the chroot after loading the TLS keys, but before opening
230 714685c1 2021-01-30 op the virtual host root directories.
231 714685c1 2021-01-30 op It's recommended to keep the TLS keys outside the chroot.
232 ae08ec7d 2021-01-25 op Future version of
234 1de92289 2021-04-15 op may enforce this.
235 2b92a447 2021-02-06 op .It Ic ipv6 Ar bool
236 2b520ad5 2021-07-09 op Enable or disable IPv6 support, off by default.
237 d19951cf 2021-07-09 op .It Ic map Ar mime-type Cm to-ext Ar file-extension
239 2b520ad5 2021-07-09 op .Ar mime-type
241 2b520ad5 2021-07-09 op .Ar file-extension .
242 2b92a447 2021-02-06 op Both argument are strings.
243 2b92a447 2021-02-06 op .It Ic port Ar portno
244 2b92a447 2021-02-06 op The port to listen on.
245 2b520ad5 2021-07-09 op 1965 by default.
246 a709ddf5 2021-02-07 op .It Ic prefork Ar number
247 a709ddf5 2021-02-07 op Run the specified number of server processes.
248 a709ddf5 2021-02-07 op This increases the performance and prevents delays when connecting to
250 2b520ad5 2021-07-09 op When not in config-less mode,
252 2b520ad5 2021-07-09 op runs 3 server processes by default.
253 2c3e53da 2021-03-03 op The maximum number allowed is 16.
254 2b92a447 2021-02-06 op .It Ic protocols Ar string
255 2b92a447 2021-02-06 op Specify the TLS protocols to enable.
257 2b92a447 2021-02-06 op .Xr tls_config_parse_protocols 3
258 2b92a447 2021-02-06 op for the valid protocol string values.
259 2b92a447 2021-02-06 op By default, both TLSv1.3 and TLSv1.2 are enabled.
262 2b92a447 2021-02-06 op to enable only TLSv1.3.
263 ae08ec7d 2021-01-25 op .It Ic user Ar string
264 ae08ec7d 2021-01-25 op Run the daemon as the given user.
267 eb699783 2021-01-18 op Every virtual host is defined by a
270 eb699783 2021-01-18 op .Bl -tag -width Ds
271 eb699783 2021-01-18 op .It Ic server Ar hostname Brq ...
272 75fbb178 2021-01-28 op Match the server name using shell globbing rules.
273 2b520ad5 2021-07-09 op It can be an explicit name,
274 de27389e 2021-01-21 op .Ar www.example.com ,
275 de27389e 2021-01-21 op or a name including a wildcards,
276 de27389e 2021-01-21 op .Ar *.example.com .
279 eb699783 2021-01-18 op Followed by a block of options that is enclosed in curly brackets:
280 eb699783 2021-01-18 op .Bl -tag -width Ds
281 cc8c2901 2021-04-29 op .It Ic alias Ar name
282 cc8c2901 2021-04-29 op Specify an additional alias
284 cc8c2901 2021-04-29 op for this server.
285 2b92a447 2021-02-06 op .It Ic auto Ic index Ar bool
286 2b92a447 2021-02-06 op If no index file is found, automatically generate a directory listing.
287 2b520ad5 2021-07-09 op Disabled by default.
288 2b92a447 2021-02-06 op .It Ic block Op Ic return Ar code Op Ar meta
289 2b92a447 2021-02-06 op Send a reply and close the connection;
296 2b520ad5 2021-07-09 op .Dq temporary failure .
299 2b92a447 2021-02-06 op is in the 3x range, then
301 2b520ad5 2021-07-09 op is mandatory.
304 2b520ad5 2021-07-09 op the following special sequences are supported:
305 fd1ae83d 2021-06-11 op .Bl -tag -width Ds -compact
307 2b92a447 2021-02-06 op is replaced with a single
310 2b92a447 2021-02-06 op is replaced with the request path.
312 2b92a447 2021-02-06 op is replaced with the query string of the request.
314 2b92a447 2021-02-06 op is replaced with the server port.
316 2b92a447 2021-02-06 op is replaced with the server name.
318 eb699783 2021-01-18 op .It Ic cert Pa file
319 eb699783 2021-01-18 op Path to the certificate to use for this server.
322 eb699783 2021-01-18 op should contain a PEM encoded certificate.
323 eb699783 2021-01-18 op This option is mandatory.
324 eb699783 2021-01-18 op .It Ic cgi Pa path
327 301e039d 2021-07-29 op scripts that matches
329 87f2b68b 2021-02-02 op using shell globbing rules.
330 6119e13e 2021-01-19 op .It Ic default type Ar string
331 6119e13e 2021-01-19 op Set the default media type that is used if the media type for a
332 6119e13e 2021-01-19 op specified extension is not found.
333 6119e13e 2021-01-19 op If not specified, the
334 6119e13e 2021-01-19 op .Ic default type
336 6119e13e 2021-01-19 op .Dq application/octet-stream .
337 2b92a447 2021-02-06 op .It Ic entrypoint Pa path
338 dafaf467 2021-04-15 op Handle all the requests for the current virtual host using the
342 2b520ad5 2021-07-09 op relative to the current document root.
343 efacb859 2021-07-09 op .It Ic env Ar name Cm = Ar value
344 9cc630aa 2021-04-28 op Set the environment variable
348 9cc630aa 2021-04-28 op when executing CGI scripts.
349 9cc630aa 2021-04-28 op Can be provided more than once.
350 8ff40039 2021-05-24 op .\" don't document the "spawn <prog>" form because it probably won't
352 762b9b99 2021-07-09 op .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
355 301e039d 2021-07-29 op instead of serving files.
358 2b520ad5 2021-07-09 op can either be a UNIX-domain socket or a TCP socket.
359 8ff40039 2021-05-24 op If the FastCGI application is listening on a UNIX domain socket,
361 8ff40039 2021-05-24 op is a local path name within the
363 8ff40039 2021-05-24 op root directory of
365 8ff40039 2021-05-24 op Otherwise, the
367 8ff40039 2021-05-24 op keyword must be provided and
369 8ff40039 2021-05-24 op is interpreted as a hostname or an IP address.
371 8ff40039 2021-05-24 op can be either a port number or the name of a service enclosed in
372 8ff40039 2021-05-24 op double quotes.
373 2b520ad5 2021-07-09 op If not specified defaults to 9000.
374 2b92a447 2021-02-06 op .It Ic index Ar string
375 2b92a447 2021-02-06 op Set the directory index file.
376 2b92a447 2021-02-06 op If not specified, it defaults to
377 2b92a447 2021-02-06 op .Pa index.gmi .
378 2b92a447 2021-02-06 op .It Ic key Pa file
379 2b92a447 2021-02-06 op Specify the private key to use for this server.
382 2b92a447 2021-02-06 op should contain a PEM encoded private key.
383 2b92a447 2021-02-06 op This option is mandatory.
384 05c23a54 2021-01-19 op .It Ic lang Ar string
385 05c23a54 2021-01-19 op Specify the language tag for the text/gemini content served.
386 05c23a54 2021-01-19 op If not specified, no
388 05c23a54 2021-01-19 op parameter will be added in the response.
389 c8b74339 2021-01-24 op .It Ic location Pa path Brq ...
390 c8b74339 2021-01-24 op Specify server configuration rules for a specific location.
393 c8b74339 2021-01-24 op argument will be matched against the request path with shell globbing
395 6016a593 2021-01-30 op In case of multiple location statements in the same context, the first
396 6016a593 2021-01-30 op matching location will be put into effect and the later ones ignored.
397 6016a593 2021-01-30 op Therefore is advisable to match for more specific paths first and for
398 6016a593 2021-01-30 op generic ones later on.
401 c8b74339 2021-01-24 op section may include most of the server configuration rules
403 3d132b28 2021-07-09 op .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
404 3d132b28 2021-07-09 op .Ic location No and Ic param .
405 2c43dcce 2021-06-17 op .It Ic log Ar bool
406 2c43dcce 2021-06-17 op Enable or disable the logging for the current server or location block.
407 efacb859 2021-07-09 op .It Ic param Ar name Cm = Ar value
408 ada16f87 2021-06-11 op Set the param
413 2b92a447 2021-02-06 op .It Ic root Pa directory
414 2b520ad5 2021-07-09 op Specify the root directory for this server
415 2b520ad5 2021-07-09 op .Pq alas the current Dq document root .
416 2b520ad5 2021-07-09 op It's relative to the chroot if enabled.
417 02be96c6 2021-02-09 op .It Ic require Ic client Ic ca Pa path
418 02be96c6 2021-02-09 op Allow requests only from clients that provide a certificate signed by
419 02be96c6 2021-02-09 op the CA certificate in
421 02be96c6 2021-02-09 op It needs to be a PEM-encoded certificate and it's not relative to the
423 6abda252 2021-02-06 op .It Ic strip Ar number
426 0773413c 2021-05-15 op components from the beginning of the path before doing a lookup in the
427 0773413c 2021-05-15 op root directory.
428 0773413c 2021-05-15 op It's also considered for the
430 2b92a447 2021-02-06 op parameter in the scope of a
431 6abda252 2021-02-06 op .Ic block return .
434 87f2b68b 2021-02-02 op When a request for an executable file matches the
436 301e039d 2021-07-29 op rule, that file will be executed and its output fed to the client.
438 ee655e64 2021-02-01 op The CGI scripts are executed in the directory they reside and inherit
439 a7b9bb4d 2021-01-24 op the environment from
441 0ed56567 2020-11-06 op with these additional variables set:
442 ee655e64 2021-02-01 op .Bl -tag -width 24m
443 28ec6178 2021-01-24 op .It Ev GATEWAY_INTERFACE
445 ee655e64 2021-02-01 op .It Ev GEMINI_DOCUMENT_ROOT
446 ee655e64 2021-02-01 op The root directory of the virtual host.
447 ee655e64 2021-02-01 op .It Ev GEMINI_SCRIPT_FILENAME
448 ee655e64 2021-02-01 op Full path to the CGI script being executed.
449 ee655e64 2021-02-01 op .It Ev GEMINI_URL
450 ee655e64 2021-02-01 op The full IRI of the request.
451 ee655e64 2021-02-01 op .It Ev GEMINI_URL_PATH
452 ee655e64 2021-02-01 op The path of the request.
453 ee655e64 2021-02-01 op .It Ev PATH_INFO
454 ee655e64 2021-02-01 op The portion of the requested path that is derived from the the IRI
455 ee655e64 2021-02-01 op path hierarchy following the part that identifies the script itself.
456 ee655e64 2021-02-01 op Can be unset.
457 ee655e64 2021-02-01 op .It Ev PATH_TRANSLATED
458 ee655e64 2021-02-01 op Present if and only if
459 ee655e64 2021-02-01 op .Ev PATH_INFO
461 ee655e64 2021-02-01 op It represent the translation of the
462 ee655e64 2021-02-01 op .Ev PATH_INFO .
464 ee655e64 2021-02-01 op builds this by appending the
465 ee655e64 2021-02-01 op .Ev PATH_INFO
466 ee655e64 2021-02-01 op to the virtual host directory root.
467 ee655e64 2021-02-01 op .It Ev QUERY_STRING
468 ee655e64 2021-02-01 op The decoded query string.
469 ee655e64 2021-02-01 op .It Ev REMOTE_ADDR , Ev REMOTE_HOST
470 ee655e64 2021-02-01 op Textual representation of the client IP.
471 ee655e64 2021-02-01 op .It Ev REQUEST_METHOD
472 ee655e64 2021-02-01 op This is present only for RFC3875 (CGI) compliance.
473 ee655e64 2021-02-01 op It's always set to the empty string.
474 ee655e64 2021-02-01 op .It Ev SCRIPT_NAME
475 ee655e64 2021-02-01 op The part of the
476 ee655e64 2021-02-01 op .Ev GEMINI_URL_PATH
477 ee655e64 2021-02-01 op that identifies the current CGI script.
478 ee655e64 2021-02-01 op .It Ev SERVER_NAME
479 ee655e64 2021-02-01 op The name of the server
480 ee655e64 2021-02-01 op .It Ev SERVER_PORT
481 ee655e64 2021-02-01 op The port the server is listening on.
482 28ec6178 2021-01-24 op .It Ev SERVER_PROTOCOL
484 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
485 ee655e64 2021-02-01 op The name and version of the server, i.e.
486 fba809b5 2021-09-19 op .Dq gmid/1.7.3
487 677afbd3 2020-12-02 op .It Ev AUTH_TYPE
488 28ec6178 2021-01-24 op The string "Certificate" if the client used a certificate, otherwise
490 677afbd3 2020-12-02 op .It Ev REMOTE_USER
491 677afbd3 2020-12-02 op The subject of the client certificate if provided, otherwise unset.
492 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_ISSUER
493 28ec6178 2021-01-24 op The is the issuer of the client certificate if provided, otherwise
495 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_HASH
496 677afbd3 2020-12-02 op The hash of the client certificate if provided, otherwise unset.
497 ee655e64 2021-02-01 op The format is
498 ee655e64 2021-02-01 op .Dq ALGO:HASH .
499 89541eee 2021-04-13 op .It Ev TLS_VERSION
500 89541eee 2021-04-13 op The TLS version negotiated with the peer.
501 89541eee 2021-04-13 op .It Ev TLS_CIPHER
502 89541eee 2021-04-13 op The cipher suite negotiated with the peer.
503 89541eee 2021-04-13 op .It Ev TLS_CIPHER_STRENGTH
504 89541eee 2021-04-13 op The strength in bits for the symmetric cipher that is being used with
506 b63e30ff 2021-02-07 op .It Ev TLS_CLIENT_NOT_AFTER
507 b63e30ff 2021-02-07 op The time corresponding to the end of the validity period of the peer
508 b63e30ff 2021-02-07 op certificate in the ISO 8601 format
509 b63e30ff 2021-02-07 op .Pq e.g. Dq 2021-02-07T20:17:41Z .
510 b63e30ff 2021-02-07 op .It Ev TLS_CLIENT_NOT_BEFORE
511 b63e30ff 2021-02-07 op The time corresponding to the start of the validity period of the peer
512 b63e30ff 2021-02-07 op certificate in the ISO 8601 format.
516 ada16f87 2021-06-11 op optionally supports FastCGI.
519 ada16f87 2021-06-11 op rule must be present in a server or location block.
520 ada16f87 2021-06-11 op Then, all requests matching that server or location will be handled
521 ada16f87 2021-06-11 op via the specified FastCGI backend.
523 ada16f87 2021-06-11 op By default the following variables
524 ada16f87 2021-06-11 op .Pq parameters
525 ada16f87 2021-06-11 op are sent, and carry the same semantics as with CGI.
526 ada16f87 2021-06-11 op More parameters can be added with the
530 ada16f87 2021-06-11 op .Bl -bullet -compact
532 ada16f87 2021-06-11 op GATEWAY_INTERFACE
534 ada16f87 2021-06-11 op GEMINI_URL_PATH
542 ada16f87 2021-06-11 op REQUEST_METHOD
546 ada16f87 2021-06-11 op SERVER_PROTOCOL
548 ada16f87 2021-06-11 op SERVER_SOFTWARE
554 ada16f87 2021-06-11 op TLS_CLIENT_ISSUER
556 ada16f87 2021-06-11 op TLS_CLIENT_HASH
562 ada16f87 2021-06-11 op TLS_CIPHER_STRENGTH
564 ada16f87 2021-06-11 op TLS_CLIENT_NOT_BEFORE
566 ada16f87 2021-06-11 op TLS_CLIENT_NOT_AFTER
569 75fbb178 2021-01-28 op To auto-detect the MIME type of the response
571 75fbb178 2021-01-28 op looks at the file extension and consults its internal table.
572 75fbb178 2021-01-28 op By default the following mappings are loaded, but they can be
573 75fbb178 2021-01-28 op overridden or extended using the
575 75fbb178 2021-01-28 op configuration option.
576 75fbb178 2021-01-28 op If no MIME is found, the value of
577 75fbb178 2021-01-28 op .Ic default type
578 75fbb178 2021-01-28 op matching the file
580 75fbb178 2021-01-28 op will be used, which is
581 75fbb178 2021-01-28 op .Dq application/octet-stream
584 75fbb178 2021-01-28 op .Bl -tag -offset indent -width 14m -compact
587 75fbb178 2021-01-28 op .It gemini, gmi
595 75fbb178 2021-01-28 op .It markdown, md
596 75fbb178 2021-01-28 op text/markdown
600 75fbb178 2021-01-28 op application/pdf
604 75fbb178 2021-01-28 op image/svg+xml
611 e58a447a 2021-07-29 op Messages and requests are logged by
615 e58a447a 2021-07-29 op facility or printed on
618 e58a447a 2021-07-29 op Requests are logged with the
621 e58a447a 2021-07-29 op Each request log entry has the following fields, separated by
624 e58a447a 2021-07-29 op .Bl -bullet -compact
626 e58a447a 2021-07-29 op Client IP address and the source port number, separated by a colon
633 e58a447a 2021-07-29 op Response status
635 e58a447a 2021-07-29 op Response meta
638 f28d96d3 2021-01-25 op Serve the current directory
639 6980aad6 2020-10-02 op .Bd -literal -offset indent
643 f28d96d3 2021-01-25 op To serve the directory
645 f28d96d3 2021-01-25 op and enable CGI scripts inside
647 0ed56567 2020-11-06 op .Bd -literal -offset indent
648 f28d96d3 2021-01-25 op $ mkdir docs/cgi
649 b7a99061 2021-04-15 op $ cat <<EOF > docs/cgi/hello
651 af5f9b27 2021-07-21 op printf "20 text/plain\er\en"
652 f28d96d3 2021-01-25 op echo "hello world"
654 f28d96d3 2021-01-25 op $ chmod +x docs/cgi/hello
655 b890467e 2021-03-20 op $ gmid -x '/cgi/*' docs
658 e308526c 2021-07-29 op An X.509 certificate must be provided to run
660 e308526c 2021-07-29 op using a configuration file.
661 e308526c 2021-07-29 op First, the RSA certificate is created using a wildcard common name:
662 e308526c 2021-07-29 op .Bd -literal -offset indent
663 e308526c 2021-07-29 op # openssl genrsa \-out /etc/ssl/private/example.com.key 4096
664 e308526c 2021-07-29 op # openssl req \-new \-x509 \-key /etc/ssl/private/example.com.key \e
665 2bb1776b 2021-07-29 op \-out /etc/ssl/example.com.crt \-days 36500 \-nodes \e
666 2bb1776b 2021-07-29 op \-subj "/CN=example.com"
667 e308526c 2021-07-29 op # chmod 600 /etc/ssl/example.com.crt
668 e308526c 2021-07-29 op # chmod 600 /etc/ssl/private/example.com.key
671 e308526c 2021-07-29 op In the example above, a certificate is valid for one hundred years from
672 e308526c 2021-07-29 op the date it was created, which is normal for TOFU.
674 eb699783 2021-01-18 op The following is an example of a possible configuration for a site
675 eb699783 2021-01-18 op that enables only TLSv1.3, adds a mime type for the file extension
677 e308526c 2021-07-29 op and defines two virtual host:
678 eb699783 2021-01-18 op .Bd -literal -offset indent
679 eb699783 2021-01-18 op ipv6 on # enable ipv6
681 eb699783 2021-01-18 op protocols "tlsv1.3"
683 d19951cf 2021-07-09 op map "application/rtf" to-ext "rtf"
685 eb699783 2021-01-18 op server "example.com" {
686 e308526c 2021-07-29 op cert "/etc/ssl/example.com.crt"
687 e308526c 2021-07-29 op key "/etc/ssl/private/example.com.key"
688 eb699783 2021-01-18 op root "/var/gemini/example.com"
691 eb699783 2021-01-18 op server "it.example.com" {
692 e308526c 2021-07-29 op cert "/etc/ssl/example.com.crt"
693 e308526c 2021-07-29 op key "/etc/ssl/private/example.com.key"
694 eb699783 2021-01-18 op root "/var/gemini/it.example.com"
696 2b520ad5 2021-07-09 op # enable cgi scripts inside "cgi-bin"
697 87f2b68b 2021-02-02 op cgi "/cgi-bin/*"
699 2b520ad5 2021-07-09 op # set the language for text/gemini files
704 f28d96d3 2021-01-25 op Yet another example, showing how to enable a
709 f28d96d3 2021-01-25 op .Bd -literal -offset indent
710 f28d96d3 2021-01-25 op chroot "/var/gemini"
713 f28d96d3 2021-01-25 op server "example.com" {
714 2b520ad5 2021-07-09 op cert "/path/to/cert.pem" # absolute path
715 2b520ad5 2021-07-09 op key "/path/to/key.pem" # also absolute
716 2b520ad5 2021-07-09 op root "/example.com" # relative to the chroot
718 4ee08bd1 2021-02-03 op location "/static/*" {
719 2b520ad5 2021-07-09 op # load the following rules only for
720 2b520ad5 2021-07-09 op # requests that matches "/static/*"
722 f28d96d3 2021-01-25 op auto index on
723 f28d96d3 2021-01-25 op index "index.gemini"
727 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
730 eb699783 2021-01-18 op .Dq Flexible and Economical
731 eb699783 2021-01-18 op UTF-8 decoder written by
732 f28d96d3 2021-01-25 op .An Bjoern Hoehrmann .
737 714685c1 2021-01-30 op program was written by
738 714685c1 2021-01-30 op .An Omar Polo Aq Mt op@omarpolo.com .
742 2b520ad5 2021-07-09 op All the root directories are opened during the daemon startup; if a
743 2b520ad5 2021-07-09 op root directory is deleted and then re-created,
745 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
746 2b520ad5 2021-07-09 op This restriction only applies to the root directories and not their
749 714685c1 2021-01-30 op a %2F sequence is indistinguishable from a literal slash: this is not
750 714685c1 2021-01-30 op RFC3986-compliant.
752 714685c1 2021-01-30 op a %00 sequence is treated as invalid character and thus rejected.
