Blob


1 .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
2 .\"
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.
6 .\"
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: July 29 2021$
15 .Dt GMID 1
16 .Os
17 .Sh NAME
18 .Nm gmid
19 .Nd simple and secure Gemini server
20 .Sh SYNOPSIS
21 .Nm
22 .Bk -words
23 .Op Fl fnv
24 .Op Fl c Ar config
25 .Op Fl D Ar macro Ns = Ns Ar value
26 .Op Fl P Ar pidfile
27 .Ek
28 .Nm
29 .Bk -words
30 .Op Fl 6hVv
31 .Op Fl d Pa certs-dir
32 .Op Fl H Ar hostname
33 .Op Fl p Ar port
34 .Op Fl x Pa cgi
35 .Op Pa dir
36 .Ek
37 .Sh DESCRIPTION
38 .Nm
39 is a simple and minimal gemini server that can serve static files,
40 execute CGI scripts and talk to FastCGI applications.
41 It can run without a configuration file with a limited set of features
42 available.
43 .Pp
44 .Nm
45 rereads the configuration file when it receives
46 .Dv SIGHUP .
47 .Pp
48 The options are as follows:
49 .Bl -tag -width 14m
50 .It Fl c Pa config
51 Specify the configuration file.
52 .It Fl D Ar macro Ns = Ns Ar value
53 Define
54 .Ar macro
55 to be set to
56 .Ar value
57 on the command line.
58 Overrides the definition of
59 .Ar macro
60 in the config file if present.
61 .It Fl f
62 Stays and logs on the foreground.
63 .It Fl n
64 Check that the configuration is valid, but don't start the server.
65 If specified two or more time, dump the configuration in addition to
66 verify it.
67 .It Fl P Pa pidfile
68 Write daemon's pid to the given location.
69 .Ar pidfile
70 will also act as lock: if another process is holding a lock on that
71 file,
72 .Nm
73 will refuse to start.
74 .El
75 .Pp
76 If no configuration file is given,
77 .Nm
78 runs in
79 .Dq config-less mode
80 .Pq i.e. runs in the foreground to serve a directory from the shell
81 and looks for the following options
82 .Bl -tag -width 14m
83 .It Fl 6
84 Enable IPv6.
85 .It Fl d Pa certs-path
86 Directory where certificates for the config-less mode are stored.
87 By default it is
88 .Pa $XDG_DATA_HOME/gmid ,
89 i.e.
90 .Pa ~/.local/share/gmid .
91 .It Fl H Ar hostname
92 The hostname
93 .Po
94 .Ar localhost
95 by default
96 .Pc .
97 Certificates for the given
98 .Ar hostname
99 are searched inside the
100 .Pa certs-dir
101 directory given with the
102 .Fl d
103 option.
104 They have the form
105 .Pa hostname.cert.pem
106 and
107 .Pa hostname.key.pem .
108 If a certificate or a key doesn't exist for a given hostname, they
109 will be generated automatically.
110 .It Fl h , Fl -help
111 Print the usage and exit.
112 .It Fl p Ar port
113 The port to listen on, by default 1965.
114 .It Fl V , Fl -version
115 Print the version and exit.
116 .It Fl v
117 Verbose mode.
118 Multiple
119 .Fl v
120 options increase the verbosity.
121 .It Fl x Pa path
122 Enable execution of
123 .Sx CGI
124 scripts.
125 See the description of the
126 .Ic cgi
127 option in the
128 .Sq Servers
129 section below to learn how
130 .Pa path
131 is processed.
132 Cannot be provided more than once.
133 .It Pa dir
134 The root directory to serve.
135 By default the current working directory is assumed.
136 .El
137 .Sh CONFIGURATION FILE
138 The configuration file is divided into three sections:
139 .Bl -tag -width xxxx
140 .It Sy Macros
141 User-defined variables may be defined and used later, simplifying the
142 configuration file.
143 .It Sy Global Options
144 Global settings for
145 .Nm .
146 .It Sy Servers
147 Virtual hosts definition.
148 .El
149 .Pp
150 Within the sections, empty lines are ignored and comments can be put
151 anywhere in the file using a hash mark
152 .Pq Sq # ,
153 and extend to the end of the current line.
154 A boolean is either the symbol
155 .Sq on
156 or
157 .Sq off .
158 A string is a sequence of characters wrapped in double quotes,
159 .Dq like this .
160 Multiple strings one next to the other are joined into a single
161 string:
162 .Bd -literal -offset indent
163 # equivalent to "temporary-failure"
164 block return 40 "temporary" "-" "failure"
165 .Ed
166 .Pp
167 Furthermore, quoting is necessary only when a string needs to contain
168 special characters
169 .Pq like spaces or punctuation ,
170 something that looks like a number or a reserved keyword.
171 The last example could have been written also as:
172 .Bd -literal -offset indent
173 block return 40 temporary "-" failure
174 .Ed
175 .Pp
176 Strict ordering of the sections is not enforced, so that is possible
177 to mix macros, options and
178 .Ic server
179 blocks.
180 However, defining all the
181 .Ic server
182 blocks after the macros and the global options is recommended.
183 .Pp
184 Newlines are often optional, except around top-level instructions, and
185 semicolons
186 .Dq \&;
187 can also be optionally used to separate options.
188 .Pp
189 Additional configuration files can be included with the
190 .Ic include
191 keyword, for example:
192 .Bd -literal -offset indent
193 include "/etc/gmid.conf.local"
194 .Ed
195 .Ss Macros
196 Macros can be defined that will later be expanded in context.
197 Macro names must start with a letter, digit or underscore and may
198 contain any of those characters.
199 Macros names may not be reserved words.
200 Macros are not expanded inside quotes.
201 .Pp
202 Two kinds of macros are supported: variable-like and proper macros.
203 When a macro is invoked with a
204 .Dq $
205 before its name its expanded as a string, whereas when it's invoked
206 with a
207 .Dq @
208 its expanded in-place.
209 .Pp
210 For example:
211 .Bd -literal -offset indent
212 dir = "/var/gemini"
213 certdir = "/etc/keys"
214 common = "lang it; auto index on"
216 server "foo" {
217 root $dir "/foo" # -> /var/gemini/foo
218 cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
219 key $certdir "/foo.pem" # -> /etc/keys/foo.pem
220 @common
222 .Ed
223 .Ss Global Options
224 .Bl -tag -width 12m
225 .It Ic chroot Pa path
226 .Xr chroot 2
227 the process to the given
228 .Pa path .
229 The daemon has to be run with root privileges and thus the option
230 .Ic user
231 needs to be provided, so privileges can be dropped.
232 Note that
233 .Nm
234 will enter the chroot after loading the TLS keys, but before opening
235 the virtual host root directories.
236 It's recommended to keep the TLS keys outside the chroot.
237 Future version of
238 .Nm
239 may enforce this.
240 .It Ic ipv6 Ar bool
241 Enable or disable IPv6 support, off by default.
242 .It Ic map Ar mime-type Cm to-ext Ar file-extension
243 Map
244 .Ar mime-type
245 to the given
246 .Ar file-extension .
247 Both argument are strings.
248 .It Ic port Ar portno
249 The port to listen on.
250 1965 by default.
251 .It Ic prefork Ar number
252 Run the specified number of server processes.
253 This increases the performance and prevents delays when connecting to
254 a server.
255 When not in config-less mode,
256 .Nm
257 runs 3 server processes by default.
258 The maximum number allowed is 16.
259 .It Ic protocols Ar string
260 Specify the TLS protocols to enable.
261 Refer to
262 .Xr tls_config_parse_protocols 3
263 for the valid protocol string values.
264 By default, both TLSv1.3 and TLSv1.2 are enabled.
265 Use
266 .Dq tlsv1.3
267 to enable only TLSv1.3.
268 .It Ic user Ar string
269 Run the daemon as the given user.
270 .El
271 .Ss Servers
272 Every virtual host is defined by a
273 .Ic server
274 block:
275 .Bl -tag -width Ds
276 .It Ic server Ar hostname Brq ...
277 Match the server name using shell globbing rules.
278 It can be an explicit name,
279 .Ar www.example.com ,
280 or a name including a wildcards,
281 .Ar *.example.com .
282 .El
283 .Pp
284 Followed by a block of options that is enclosed in curly brackets:
285 .Bl -tag -width Ds
286 .It Ic alias Ar name
287 Specify an additional alias
288 .Ar name
289 for this server.
290 .It Ic auto Ic index Ar bool
291 If no index file is found, automatically generate a directory listing.
292 Disabled by default.
293 .It Ic block Op Ic return Ar code Op Ar meta
294 Send a reply and close the connection;
295 by default
296 .Ar code
297 is 40
298 and
299 .Ar meta
300 is
301 .Dq temporary failure .
302 If
303 .Ar code
304 is in the 3x range, then
305 .Ar meta
306 is mandatory.
307 Inside
308 .Ar meta ,
309 the following special sequences are supported:
310 .Bl -tag -width Ds -compact
311 .It \&%\&%
312 is replaced with a single
313 .Sq \&% .
314 .It \&%p
315 is replaced with the request path.
316 .It \&%q
317 is replaced with the query string of the request.
318 .It \&%P
319 is replaced with the server port.
320 .It \&%N
321 is replaced with the server name.
322 .El
323 .It Ic cert Pa file
324 Path to the certificate to use for this server.
325 The
326 .Pa file
327 should contain a PEM encoded certificate.
328 This option is mandatory.
329 .It Ic cgi Pa path
330 Execute
331 .Sx CGI
332 scripts that matches
333 .Pa path
334 using shell globbing rules.
335 .It Ic default type Ar string
336 Set the default media type that is used if the media type for a
337 specified extension is not found.
338 If not specified, the
339 .Ic default type
340 is set to
341 .Dq application/octet-stream .
342 .It Ic entrypoint Pa path
343 Handle all the requests for the current virtual host using the
344 .Sx CGI
345 script at
346 .Pa path ,
347 relative to the current document root.
348 .It Ic env Ar name Cm = Ar value
349 Set the environment variable
350 .Ar name
351 to
352 .Ar value
353 when executing CGI scripts.
354 Can be provided more than once.
355 .\" don't document the "spawn <prog>" form because it probably won't
356 .\" be kept.
357 .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
358 Enable
359 .Sx FastCGI
360 instead of serving files.
361 The
362 .Pa socket
363 can either be a UNIX-domain socket or a TCP socket.
364 If the FastCGI application is listening on a UNIX domain socket,
365 .Pa socket
366 is a local path name within the
367 .Xr chroot 2
368 root directory of
369 .Nm .
370 Otherwise, the
371 .Ic tcp
372 keyword must be provided and
373 .Pa socket
374 is interpreted as a hostname or an IP address.
375 .Ar port
376 can be either a port number or the name of a service enclosed in
377 double quotes.
378 If not specified defaults to 9000.
379 .It Ic index Ar string
380 Set the directory index file.
381 If not specified, it defaults to
382 .Pa index.gmi .
383 .It Ic key Pa file
384 Specify the private key to use for this server.
385 The
386 .Pa file
387 should contain a PEM encoded private key.
388 This option is mandatory.
389 .It Ic lang Ar string
390 Specify the language tag for the text/gemini content served.
391 If not specified, no
392 .Dq lang
393 parameter will be added in the response.
394 .It Ic location Pa path Brq ...
395 Specify server configuration rules for a specific location.
396 The
397 .Pa path
398 argument will be matched against the request path with shell globbing
399 rules.
400 In case of multiple location statements in the same context, the first
401 matching location will be put into effect and the later ones ignored.
402 Therefore is advisable to match for more specific paths first and for
403 generic ones later on.
405 .Ic location
406 section may include most of the server configuration rules
407 except
408 .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
409 .Ic location No and Ic param .
410 .It Ic log Ar bool
411 Enable or disable the logging for the current server or location block.
412 .It Ic param Ar name Cm = Ar value
413 Set the param
414 .Ar name
415 to
416 .Ar value
417 for FastCGI.
418 .It Ic ocsp Ar file
419 Specify an OCSP response to be stapled during TLS handshakes
420 with this server.
421 The
422 .Ar file
423 should contain a DER-format OCSP response retrieved from an
424 OCSP server for the
425 .Ic cert
426 in use.
427 If the OCSP response in
428 .Ar file
429 is empty, OCSP stapling will not be used.
430 The default is to not use OCSP stapling.
431 .It Ic root Pa directory
432 Specify the root directory for this server
433 .Pq alas the current Dq document root .
434 It's relative to the chroot if enabled.
435 .It Ic require Ic client Ic ca Pa path
436 Allow requests only from clients that provide a certificate signed by
437 the CA certificate in
438 .Pa path .
439 It needs to be a PEM-encoded certificate and it's not relative to the
440 chroot.
441 .It Ic strip Ar number
442 Strip
443 .Ar number
444 components from the beginning of the path before doing a lookup in the
445 root directory.
446 It's also considered for the
447 .Ar meta
448 parameter in the scope of a
449 .Ic block return .
450 .El
451 .Sh CGI
452 When a request for an executable file matches the
453 .Ic cgi
454 rule, that file will be executed and its output fed to the client.
455 .Pp
456 The CGI scripts are executed in the directory they reside and inherit
457 the environment from
458 .Nm
459 with these additional variables set:
460 .Bl -tag -width 24m
461 .It Ev GATEWAY_INTERFACE
462 .Dq CGI/1.1
463 .It Ev GEMINI_DOCUMENT_ROOT
464 The root directory of the virtual host.
465 .It Ev GEMINI_SCRIPT_FILENAME
466 Full path to the CGI script being executed.
467 .It Ev GEMINI_URL
468 The full IRI of the request.
469 .It Ev GEMINI_URL_PATH
470 The path of the request.
471 .It Ev PATH_INFO
472 The portion of the requested path that is derived from the the IRI
473 path hierarchy following the part that identifies the script itself.
474 Can be unset.
475 .It Ev PATH_TRANSLATED
476 Present if and only if
477 .Ev PATH_INFO
478 is set.
479 It represent the translation of the
480 .Ev PATH_INFO .
481 .Nm
482 builds this by appending the
483 .Ev PATH_INFO
484 to the virtual host directory root.
485 .It Ev QUERY_STRING
486 The decoded query string.
487 .It Ev REMOTE_ADDR , Ev REMOTE_HOST
488 Textual representation of the client IP.
489 .It Ev REQUEST_METHOD
490 This is present only for RFC3875 (CGI) compliance.
491 It's always set to the empty string.
492 .It Ev SCRIPT_NAME
493 The part of the
494 .Ev GEMINI_URL_PATH
495 that identifies the current CGI script.
496 .It Ev SERVER_NAME
497 The name of the server
498 .It Ev SERVER_PORT
499 The port the server is listening on.
500 .It Ev SERVER_PROTOCOL
501 .Dq GEMINI
502 .It Ev SERVER_SOFTWARE
503 The name and version of the server, i.e.
504 .Dq gmid/1.7.3
505 .It Ev AUTH_TYPE
506 The string "Certificate" if the client used a certificate, otherwise
507 unset.
508 .It Ev REMOTE_USER
509 The subject of the client certificate if provided, otherwise unset.
510 .It Ev TLS_CLIENT_ISSUER
511 The is the issuer of the client certificate if provided, otherwise
512 unset.
513 .It Ev TLS_CLIENT_HASH
514 The hash of the client certificate if provided, otherwise unset.
515 The format is
516 .Dq ALGO:HASH .
517 .It Ev TLS_VERSION
518 The TLS version negotiated with the peer.
519 .It Ev TLS_CIPHER
520 The cipher suite negotiated with the peer.
521 .It Ev TLS_CIPHER_STRENGTH
522 The strength in bits for the symmetric cipher that is being used with
523 the peer.
524 .It Ev TLS_CLIENT_NOT_AFTER
525 The time corresponding to the end of the validity period of the peer
526 certificate in the ISO 8601 format
527 .Pq e.g. Dq 2021-02-07T20:17:41Z .
528 .It Ev TLS_CLIENT_NOT_BEFORE
529 The time corresponding to the start of the validity period of the peer
530 certificate in the ISO 8601 format.
531 .El
532 .Sh FastCGI
533 .Nm
534 optionally supports FastCGI.
536 .Ic fastcgi
537 rule must be present in a server or location block.
538 Then, all requests matching that server or location will be handled
539 via the specified FastCGI backend.
540 .Pp
541 By default the following variables
542 .Pq parameters
543 are sent, and carry the same semantics as with CGI.
544 More parameters can be added with the
545 .Ic param
546 option.
547 .Pp
548 .Bl -bullet -compact
549 .It
550 GATEWAY_INTERFACE
551 .It
552 GEMINI_URL_PATH
553 .It
554 QUERY_STRING
555 .It
556 REMOTE_ADDR
557 .It
558 REMOTE_HOST
559 .It
560 REQUEST_METHOD
561 .It
562 SERVER_NAME
563 .It
564 SERVER_PROTOCOL
565 .It
566 SERVER_SOFTWARE
567 .It
568 AUTH_TYPE
569 .It
570 REMOTE_USER
571 .It
572 TLS_CLIENT_ISSUER
573 .It
574 TLS_CLIENT_HASH
575 .It
576 TLS_VERSION
577 .It
578 TLS_CIPHER
579 .It
580 TLS_CIPHER_STRENGTH
581 .It
582 TLS_CLIENT_NOT_BEFORE
583 .It
584 TLS_CLIENT_NOT_AFTER
585 .El
586 .Sh MIME
587 To auto-detect the MIME type of the response
588 .Nm
589 looks at the file extension and consults its internal table.
590 By default the following mappings are loaded, but they can be
591 overridden or extended using the
592 .Ic map
593 configuration option.
594 If no MIME is found, the value of
595 .Ic default type
596 matching the file
597 .Ic location
598 will be used, which is
599 .Dq application/octet-stream
600 by default.
601 .Pp
602 .Bl -tag -offset indent -width 14m -compact
603 .It diff
604 text/x-patch
605 .It gemini, gmi
606 text/gemini
607 .It gif
608 image/gif
609 .It jpeg
610 image/jpeg
611 .It jpg
612 image/jpeg
613 .It markdown, md
614 text/markdown
615 .It patch
616 text/x-patch
617 .It pdf
618 application/pdf
619 .It png
620 image/png
621 .It svg
622 image/svg+xml
623 .It txt
624 text/plain
625 .It xml
626 text/xml
627 .El
628 .Sh LOGGING
629 Messages and requests are logged by
630 .Xr syslog 3
631 using the
632 .Dv DAEMON
633 facility or printed on
634 .Em stderr .
635 .Pp
636 Requests are logged with the
637 .Dv NOTICE
638 severity.
639 Each request log entry has the following fields, separated by
640 whitespace:
641 .Pp
642 .Bl -bullet -compact
643 .It
644 Client IP address and the source port number, separated by a colon
645 .It
646 .Sy GET
647 keyword
648 .It
649 Request URL
650 .It
651 Response status
652 .It
653 Response meta
654 .El
655 .Sh EXAMPLES
656 Serve the current directory
657 .Bd -literal -offset indent
658 $ gmid .
659 .Ed
660 .Pp
661 To serve the directory
662 .Pa docs
663 and enable CGI scripts inside
664 .Pa docs/cgi
665 .Bd -literal -offset indent
666 $ mkdir docs/cgi
667 $ cat <<EOF > docs/cgi/hello
668 #!/bin/sh
669 printf "20 text/plain\er\en"
670 echo "hello world"
671 EOF
672 $ chmod +x docs/cgi/hello
673 $ gmid -x '/cgi/*' docs
674 .Ed
675 .Pp
676 An X.509 certificate must be provided to run
677 .Nm
678 using a configuration file.
679 First, the RSA certificate is created using a wildcard common name:
680 .Bd -literal -offset indent
681 # openssl genrsa \-out /etc/ssl/private/example.com.key 4096
682 # openssl req \-new \-x509 \e
683 \-key /etc/ssl/private/example.com.key \e
684 \-out /etc/ssl/example.com.crt \e
685 \-days 36500 \-nodes \e
686 \-subj "/CN=example.com"
687 # chmod 600 /etc/ssl/example.com.crt
688 # chmod 600 /etc/ssl/private/example.com.key
689 .Ed
690 .Pp
691 In the example above, a certificate is valid for one hundred years from
692 the date it was created, which is normal for TOFU.
693 .Pp
694 The following is an example of a possible configuration for a site
695 that enables only TLSv1.3, adds a mime type for the file extension
696 .Qq rtf
697 and defines two virtual host:
698 .Bd -literal -offset indent
699 ipv6 on # enable ipv6
701 protocols "tlsv1.3"
703 map "application/rtf" to-ext "rtf"
705 server "example.com" {
706 cert "/etc/ssl/example.com.crt"
707 key "/etc/ssl/private/example.com.key"
708 root "/var/gemini/example.com"
711 server "it.example.com" {
712 cert "/etc/ssl/example.com.crt"
713 key "/etc/ssl/private/example.com.key"
714 root "/var/gemini/it.example.com"
716 # enable cgi scripts inside "cgi-bin"
717 cgi "/cgi-bin/*"
719 # set the language for text/gemini files
720 lang "it"
722 .Ed
723 .Pp
724 Yet another example, showing how to enable a
725 .Ic chroot
726 and use
727 .Ic location
728 rule
729 .Bd -literal -offset indent
730 chroot "/var/gemini"
731 user "_gmid"
733 server "example.com" {
734 cert "/path/to/cert.pem" # absolute path
735 key "/path/to/key.pem" # also absolute
736 root "/example.com" # relative to the chroot
738 location "/static/*" {
739 # load the following rules only for
740 # requests that matches "/static/*"
742 auto index on
743 index "index.gemini"
746 .Ed
747 .Sh ACKNOWLEDGEMENTS
748 .Nm
749 uses the
750 .Dq Flexible and Economical
751 UTF-8 decoder written by
752 .An Bjoern Hoehrmann .
753 .Sh AUTHORS
754 .An -nosplit
755 The
756 .Nm
757 program was written by
758 .An Omar Polo Aq Mt op@omarpolo.com .
759 .Sh CAVEATS
760 .Bl -bullet
761 .It
762 All the root directories are opened during the daemon startup; if a
763 root directory is deleted and then re-created,
764 .Nm
765 won't be able to serve files inside that directory until a restart.
766 This restriction only applies to the root directories and not their
767 content.
768 .It
769 a %2F sequence is indistinguishable from a literal slash: this is not
770 RFC3986-compliant.
771 .It
772 a %00 sequence is treated as invalid character and thus rejected.
773 .El