1
.\" Copyright (c) 2022 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: April 7 2022$
15
.Dt GMID.CONF 5
16
.Os
17
.Sh NAME
18
.Nm gmid.conf
19
.Nd gmid Gemini server configuration file
20
.Sh DESCRIPTION
21
.Nm
22
is the configuration file format for the
23
.Xr gmid 1
24
Gemini server.
25
.Pp
26
The configuration file is divided into three sections:
27
.Bl -tag -width xxxx
28
.It Sy Macros
29
User-defined variables may be defined and used later, simplifying the
30
configuration file.
31
.It Sy Global Options
32
Global settings for
33
.Nm .
34
.It Sy Servers
35
Virtual hosts definition.
36
.It Sy Types
37
Media types and extensions.
38
.El
39
.Pp
40
Within the sections, empty lines are ignored and comments can be put
41
anywhere in the file using a hash mark
42
.Pq Sq # ,
43
and extend to the end of the current line.
44
A boolean is either the symbol
45
.Sq on
46
or
47
.Sq off .
48
A string is a sequence of characters wrapped in double quotes,
49
.Dq like this .
50
Multiple strings one next to the other are joined into a single
51
string:
52
.Bd -literal -offset indent
53
# equivalent to "temporary-failure"
54
block return 40 "temporary" "-" "failure"
55
.Ed
56
.Pp
57
Furthermore, quoting is necessary only when a string needs to contain
58
special characters
59
.Pq like spaces or punctuation ,
60
something that looks like a number or a reserved keyword.
61
The last example could have been written also as:
62
.Bd -literal -offset indent
63
block return 40 temporary "-" failure
64
.Ed
65
.Pp
66
Strict ordering of the sections is not enforced, so that is possible
67
to mix macros, options and
68
.Ic server
69
blocks.
70
However, defining all the
71
.Ic server
72
blocks after the macros and the global options is recommended.
73
.Pp
74
Newlines are often optional, except around top-level instructions, and
75
semicolons
76
.Dq \&;
77
can also be optionally used to separate options.
78
.Pp
79
Additional configuration files can be included with the
80
.Ic include
81
keyword, for example:
82
.Bd -literal -offset indent
83
include "/etc/gmid.conf.local"
84
.Ed
85
.Ss Macros
86
Macros can be defined that will later be expanded in context.
87
Macro names must start with a letter, digit or underscore and may
88
contain any of those characters.
89
Macros names may not be reserved words.
90
Macros are not expanded inside quotes.
91
.Pp
92
Two kinds of macros are supported: variable-like and proper macros.
93
When a macro is invoked with a
94
.Dq $
95
before its name its expanded as a string, whereas when it's invoked
96
with a
97
.Dq @
98
its expanded in-place.
99
.Pp
100
For example:
101
.Bd -literal -offset indent
102
dir = "/var/gemini"
103
certdir = "/etc/keys"
104
common = "lang it; auto index on"
105

106
server "foo" {
107
	root $dir "/foo"         # -> /var/gemini/foo
108
	cert $certdir "/foo.pem" # -> /etc/keys/foo.pem
109
	key  $certdir "/foo.key" # -> /etc/keys/foo.key
110
	@common
111
}
112
.Ed
113
.Ss Global Options
114
.Bl -tag -width 12m
115
.It Ic chroot Ar path
116
.Xr chroot 2
117
the process to the given
118
.Ar path .
119
The daemon has to be run with root privileges and thus the option
120
.Ic user
121
needs to be provided, so privileges can be dropped.
122
Note that
123
.Nm
124
will enter the chroot after loading the TLS keys, but before opening
125
the virtual host root directories.
126
It's recommended to keep the TLS keys outside the chroot.
127
Future version of
128
.Nm
129
may enforce this.
130
.It Ic ipv6 Ar bool
131
Enable or disable IPv6 support, off by default.
132
.It Ic port Ar portno
133
The port to listen on.
134
1965 by default.
135
.It Ic prefork Ar number
136
Run the specified number of server processes.
137
This increases the performance and prevents delays when connecting to
138
a server.
139
When not in config-less mode,
140
.Nm
141
runs 3 server processes by default.
142
The maximum number allowed is 16.
143
.It Ic protocols Ar string
144
Specify the TLS protocols to enable.
145
Refer to
146
.Xr tls_config_parse_protocols 3
147
for the valid protocol string values.
148
By default, both TLSv1.3 and TLSv1.2 are enabled.
149
Use
150
.Dq tlsv1.3
151
to enable only TLSv1.3.
152
.It Ic user Ar string
153
Run the daemon as the given user.
154
.El
155
.Ss Servers
156
Every virtual host is defined by a
157
.Ic server
158
block:
159
.Bl -tag -width Ds
160
.It Ic server Ar hostname Brq ...
161
Match the server name using shell globbing rules.
162
It can be an explicit name,
163
.Ar www.example.com ,
164
or a name including a wildcards,
165
.Ar *.example.com .
166
.El
167
.Pp
168
Followed by a block of options that is enclosed in curly brackets:
169
.Bl -tag -width Ds
170
.It Ic alias Ar name
171
Specify an additional alias
172
.Ar name
173
for this server.
174
.It Ic auto Ic index Ar bool
175
If no index file is found, automatically generate a directory listing.
176
Disabled by default.
177
.It Ic block Op Ic return Ar code Op Ar meta
178
Send a reply and close the connection;
179
by default
180
.Ar code
181
is 40
182
and
183
.Ar meta
184
is
185
.Dq temporary failure .
186
If
187
.Ar code
188
is in the 3x range, then
189
.Ar meta
190
is mandatory.
191
Inside
192
.Ar meta ,
193
the following special sequences are supported:
194
.Bl -tag -width Ds -compact
195
.It \&%\&%
196
is replaced with a single
197
.Sq \&% .
198
.It \&%p
199
is replaced with the request path.
200
.It \&%q
201
is replaced with the query string of the request.
202
.It \&%P
203
is replaced with the server port.
204
.It \&%N
205
is replaced with the server name.
206
.El
207
.It Ic cert Ar file
208
Path to the certificate to use for this server.
209
.Ar file
210
should contain a PEM encoded certificate.
211
This option is mandatory.
212
.It Ic cgi Ar path
213
Execute
214
.Sx CGI
215
scripts that matches
216
.Ar path
217
using shell globbing rules.
218
.Pp
219
The CGI scripts are executed in the directory they reside and inherit
220
the environment from
221
.Nm gmid
222
with these additional variables set:
223
.Bl -tag -width 24m
224
.It Ev GATEWAY_INTERFACE
225
.Dq CGI/1.1
226
.It Ev GEMINI_DOCUMENT_ROOT
227
The root directory of the virtual host.
228
.It Ev GEMINI_SCRIPT_FILENAME
229
Full path to the CGI script being executed.
230
.It Ev GEMINI_URL
231
The full IRI of the request.
232
.It Ev GEMINI_URL_PATH
233
The path of the request.
234
.It Ev PATH_INFO
235
The portion of the requested path that is derived from the the IRI
236
path hierarchy following the part that identifies the script itself.
237
Can be unset.
238
.It Ev PATH_TRANSLATED
239
Present if and only if
240
.Ev PATH_INFO
241
is set.
242
It represent the translation of the
243
.Ev PATH_INFO .
244
.Nm gmid
245
builds this by appending the
246
.Ev PATH_INFO
247
to the virtual host directory root.
248
.It Ev QUERY_STRING
249
The decoded query string.
250
.It Ev REMOTE_ADDR , Ev REMOTE_HOST
251
Textual representation of the client IP.
252
.It Ev REQUEST_METHOD
253
This is present only for RFC3875 (CGI) compliance.
254
It's always set to the empty string.
255
.It Ev SCRIPT_NAME
256
The part of the
257
.Ev GEMINI_URL_PATH
258
that identifies the current CGI script.
259
.It Ev SERVER_NAME
260
The name of the server
261
.It Ev SERVER_PORT
262
The port the server is listening on.
263
.It Ev SERVER_PROTOCOL
264
.Dq GEMINI
265
.It Ev SERVER_SOFTWARE
266
The name and version of the server, i.e.
267
.Dq gmid/1.8.3
268
.It Ev AUTH_TYPE
269
The string "Certificate" if the client used a certificate, otherwise
270
unset.
271
.It Ev REMOTE_USER
272
The subject of the client certificate if provided, otherwise unset.
273
.It Ev TLS_CLIENT_ISSUER
274
The is the issuer of the client certificate if provided, otherwise
275
unset.
276
.It Ev TLS_CLIENT_HASH
277
The hash of the client certificate if provided, otherwise unset.
278
The format is
279
.Dq ALGO:HASH .
280
.It Ev TLS_VERSION
281
The TLS version negotiated with the peer.
282
.It Ev TLS_CIPHER
283
The cipher suite negotiated with the peer.
284
.It Ev TLS_CIPHER_STRENGTH
285
The strength in bits for the symmetric cipher that is being used with
286
the peer.
287
.It Ev TLS_CLIENT_NOT_AFTER
288
The time corresponding to the end of the validity period of the peer
289
certificate in the ISO 8601 format
290
.Pq e.g. Dq 2021-02-07T20:17:41Z .
291
.It Ev TLS_CLIENT_NOT_BEFORE
292
The time corresponding to the start of the validity period of the peer
293
certificate in the ISO 8601 format.
294
.El
295
.It Ic default type Ar string
296
Set the default media type that is used if the media type for a
297
specified extension is not found.
298
If not specified, the
299
.Ic default type
300
is set to
301
.Dq application/octet-stream .
302
.It Ic entrypoint Ar path
303
Handle all the requests for the current virtual host using the
304
.Sx CGI
305
script at
306
.Ar path ,
307
relative to the current document root.
308
.It Ic env Ar name Cm = Ar value
309
Set the environment variable
310
.Ar name
311
to
312
.Ar value
313
when executing CGI scripts.
314
Can be provided more than once.
315
.\" don't document the "spawn <prog>" form because it probably won't
316
.\" be kept.
317
.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
318
Enable
319
.Sx FastCGI
320
instead of serving files.
321
The
322
.Ar socket
323
can either be a UNIX-domain socket or a TCP socket.
324
If the FastCGI application is listening on a UNIX domain socket,
325
.Ar socket
326
is a local path name within the
327
.Xr chroot 2
328
root directory of
329
.Nm .
330
Otherwise, the
331
.Ic tcp
332
keyword must be provided and
333
.Ar socket
334
is interpreted as a hostname or an IP address.
335
.Ar port
336
can be either a port number or the name of a service enclosed in
337
double quotes.
338
If not specified defaults to 9000.
339
.It Ic index Ar string
340
Set the directory index file.
341
If not specified, it defaults to
342
.Pa index.gmi .
343
.It Ic key Ar file
344
Specify the private key to use for this server.
345
.Ar file
346
should contain a PEM encoded private key.
347
This option is mandatory.
348
.It Ic lang Ar string
349
Specify the language tag for the text/gemini content served.
350
If not specified, no
351
.Dq lang
352
parameter will be added in the response.
353
.It Ic location Ar path Brq ...
354
Specify server configuration rules for a specific location.
355
.Ar path
356
argument will be matched against the request path with shell globbing
357
rules.
358
In case of multiple location statements in the same context, the first
359
matching location will be put into effect and the later ones ignored.
360
Therefore is advisable to match for more specific paths first and for
361
generic ones later on.
362
A
363
.Ic location
364
section may include most of the server configuration rules
365
except
366
.Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
367
.Ic location , Ic param No and Ic proxy .
368
.It Ic log Ar bool
369
Enable or disable the logging for the current server or location block.
370
.It Ic param Ar name Cm = Ar value
371
Set the param
372
.Ar name
373
to
374
.Ar value
375
for FastCGI.
376
By default the following variables
377
.Pq parameters
378
are sent, and carry the same semantics as with CGI:
379
.Pp
380
.Bl -bullet -compact
381
.It
382
GATEWAY_INTERFACE
383
.It
384
GEMINI_URL_PATH
385
.It
386
QUERY_STRING
387
.It
388
REMOTE_ADDR
389
.It
390
REMOTE_HOST
391
.It
392
REQUEST_METHOD
393
.It
394
SERVER_NAME
395
.It
396
SERVER_PROTOCOL
397
.It
398
SERVER_SOFTWARE
399
.It
400
AUTH_TYPE
401
.It
402
REMOTE_USER
403
.It
404
TLS_CLIENT_ISSUER
405
.It
406
TLS_CLIENT_HASH
407
.It
408
TLS_VERSION
409
.It
410
TLS_CIPHER
411
.It
412
TLS_CIPHER_STRENGTH
413
.It
414
TLS_CLIENT_NOT_BEFORE
415
.It
416
TLS_CLIENT_NOT_AFTER
417
.El
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 proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
432
Set up a reverse proxy.
433
The optional matching rules
434
.Cm proto
435
and
436
.Cm for-host
437
can be used to enable proxying only for protocols matching
438
.Ar name
439
.Po Dq gemini
440
by default
441
.Pc
442
and/or whose request IRI matches
443
.Ar host
444
and
445
.Ar port
446
.Pq 1965 by default .
447
Matching happens using shell globbing rules.
448
.Pp
449
In case of multiple matching proxy blocks in the same context, the
450
first matching proxy will be put into effect and the later ones
451
ignored.
452
.Pp
453
Valid options are:
454
.Bl -tag -width Ds
455
.It Ic cert Ar file
456
Specify the client certificate to use when making requests.
457
.It Ic key Ar file
458
Specify the client certificate key to use when making requests.
459
.It Ic protocols Ar string
460
Specify the TLS protocols allowed when making remote requests.
461
Refer to the
462
.Xr tls_config_parse_protocols 3
463
function for the valid protocol string values.
464
By default, both TLSv1.2 and TLSv1.3 are enabled.
465
.It Ic relay-to Ar host : Ns Op Ar port
466
Relay the request to the given
467
.Ar host
468
at the given
469
.Ar port ,
470
1965 by default.
471
This is the only mandatory option in a
472
.Ic proxy
473
block.
474
.It Ic require Ic client Ic ca Ar file
475
Allow the proxying only from clients that provide a certificate
476
signed by the CA certificate in
477
.Ar file .
478
.It Ic sni Ar hostname
479
Use the given
480
.Ar hostname
481
instead of the one extracted from the
482
.Ic relay-to
483
rule for the TLS handshake with the proxied gemini server.
484
.It Ic use-tls Ar bool
485
Specify whether to use TLS when connecting to the proxied host.
486
Enabled by default.
487
.It Ic verifyname Ar bool
488
Enable or disable the TLS server name verification.
489
Enabled by default.
490
.El
491
.It Ic root Ar directory
492
Specify the root directory for this server
493
.Pq alas the current Dq document root .
494
It's relative to the chroot if enabled.
495
.It Ic require Ic client Ic ca Ar path
496
Allow requests only from clients that provide a certificate signed by
497
the CA certificate in
498
.Ar path .
499
It needs to be a PEM-encoded certificate and it's not relative to the
500
chroot.
501
.It Ic strip Ar number
502
Strip
503
.Ar number
504
components from the beginning of the path before doing a lookup in the
505
root directory.
506
It's also considered for the
507
.Ar meta
508
parameter in the scope of a
509
.Ic block return .
510
.El
511
.Ss Types
512
The
513
.Ic types
514
section must include one or more lines of the following syntax, enclosed
515
in curly brances:
516
.Bl -tag -width Ds
517
.It Ar type/subtype Ar name Op Ar name ...
518
Set the media
519
.Ar type
520
and
521
.Ar subtype
522
to the specified extension
523
.Ar name .
524
One or more names can be specified per line.
525
Earch line may end with an optional semicolon.
526
.It Ic include Ar file
527
Include types definition from an external file, for example
528
.Pa /usr/share/misc/mime.types .
529
.El
530
.Pp
531
By default
532
.Nm gmid
533
has built-in media types for
534
.Bl -tag -offset indent -width 15m -compact
535
.It application/pdf
536
pdf
537
.It image/gif
538
gif
539
.It image/jpeg
540
jpg jpeg
541
.It image/png
542
png
543
.It image/svg+xml
544
svg
545
.It text/gemini
546
gemini gmi
547
.It text/markdown
548
markdown md
549
.It text/x-patch
550
diff patch
551
.It text/xml
552
xml
553
.El
554
.Sh EXAMPLES
555
The following is an example of a possible configuration for a site
556
that enables only TLSv1.3, adds the MIME types mapping from
557
.Pa /usr/share/misc/mime.types
558
and defines two virtual host:
559
.Bd -literal -offset indent
560
ipv6 on		# enable ipv6
561

562
protocols "tlsv1.3"
563

564
types {
565
	include "/usr/share/misc/mime.types"
566
}
567

568
server "example.com" {
569
	cert "/etc/ssl/example.com.pem"
570
	key  "/etc/ssl/private/example.com.key"
571
	root "/var/gemini/example.com"
572
}
573

574
server "example.it" {
575
	cert "/etc/ssl/example.it.pem"
576
	key  "/etc/ssl/private/example.it.key"
577
	root "/var/gemini/example.it"
578

579
	# execute cgi scripts inside "cgi-bin"
580
	cgi  "/cgi-bin/*"
581

582
	# set the language for text/gemini files
583
	lang "it"
584
}
585
.Ed
586
.Pp
587
Yet another example, showing how to enable a
588
.Ic chroot
589
and use
590
.Ic location
591
rule
592
.Bd -literal -offset indent
593
chroot "/var/gemini"
594
user "_gmid"
595

596
server "example.com" {
597
	# absolute paths:
598
	cert "/etc/ssl/example.com.pem"
599
	key  "/etc/ssl/private/example.com.key"
600

601
	# relative to the chroot:
602
	root "/example.com"
603

604
	location "/static/*" {
605
		# load the following rules only for
606
		# requests that matches "/static/*"
607

608
		auto index on
609
		index "index.gemini"
610
	}
611
}
612
.Ed
613
.Sh SEE ALSO
614
.Xr gmid 1 ,
615
.Xr slowcgi 8
616
.Sh AUTHORS
617
.An -nosplit
618
The
619
.Nm gmid
620
program was written by
621
.An Omar Polo Aq Mt op@omarpolo.com .