Blame
Date:
Mon Jul 4 14:51:39 2022 UTC
Message:
changes for 1.8.4
001
2022-04-07
op
.\" Copyright (c) 2022 Omar Polo <op@omarpolo.com>
002
2022-04-07
op
.\"
003
2022-04-07
op
.\" Permission to use, copy, modify, and distribute this software for any
004
2022-04-07
op
.\" purpose with or without fee is hereby granted, provided that the above
005
2022-04-07
op
.\" copyright notice and this permission notice appear in all copies.
006
2022-04-07
op
.\"
007
2022-04-07
op
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
008
2022-04-07
op
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
009
2022-04-07
op
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
010
2022-04-07
op
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
011
2022-04-07
op
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
012
2022-04-07
op
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
013
2022-04-07
op
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
014
2022-04-07
op
.Dd $Mdocdate: April 7 2022$
015
2022-04-07
op
.Dt GMID.CONF 5
016
2022-04-07
op
.Os
017
2022-04-07
op
.Sh NAME
018
2022-04-07
op
.Nm gmid.conf
019
2022-04-07
op
.Nd gmid Gemini server configuration file
020
2022-04-07
op
.Sh DESCRIPTION
021
2022-04-07
op
.Nm
022
2022-04-07
op
is the configuration file format for the
023
2022-04-07
op
.Xr gmid 1
024
2022-04-07
op
Gemini server.
025
2022-04-07
op
.Pp
026
2022-04-07
op
The configuration file is divided into three sections:
027
2022-04-07
op
.Bl -tag -width xxxx
028
2022-04-07
op
.It Sy Macros
029
2022-04-07
op
User-defined variables may be defined and used later, simplifying the
030
2022-04-07
op
configuration file.
031
2022-04-07
op
.It Sy Global Options
032
2022-04-07
op
Global settings for
033
2022-04-07
op
.Nm .
034
2022-04-07
op
.It Sy Servers
035
2022-04-07
op
Virtual hosts definition.
036
2022-04-07
op
.It Sy Types
037
2022-04-07
op
Media types and extensions.
038
2022-04-07
op
.El
039
2022-04-07
op
.Pp
040
2022-04-07
op
Within the sections, empty lines are ignored and comments can be put
041
2022-04-07
op
anywhere in the file using a hash mark
042
2022-04-07
op
.Pq Sq # ,
043
2022-04-07
op
and extend to the end of the current line.
044
2022-04-07
op
A boolean is either the symbol
045
2022-04-07
op
.Sq on
046
2022-04-07
op
or
047
2022-04-07
op
.Sq off .
048
2022-04-07
op
A string is a sequence of characters wrapped in double quotes,
049
2022-04-07
op
.Dq like this .
050
2022-04-07
op
Multiple strings one next to the other are joined into a single
051
2022-04-07
op
string:
052
2022-04-07
op
.Bd -literal -offset indent
053
2022-04-07
op
# equivalent to "temporary-failure"
054
2022-04-07
op
block return 40 "temporary" "-" "failure"
055
2022-04-07
op
.Ed
056
2022-04-07
op
.Pp
057
2022-04-07
op
Furthermore, quoting is necessary only when a string needs to contain
058
2022-04-07
op
special characters
059
2022-04-07
op
.Pq like spaces or punctuation ,
060
2022-04-07
op
something that looks like a number or a reserved keyword.
061
2022-04-07
op
The last example could have been written also as:
062
2022-04-07
op
.Bd -literal -offset indent
063
2022-04-07
op
block return 40 temporary "-" failure
064
2022-04-07
op
.Ed
065
2022-04-07
op
.Pp
066
2022-04-07
op
Strict ordering of the sections is not enforced, so that is possible
067
2022-04-07
op
to mix macros, options and
068
2022-04-07
op
.Ic server
069
2022-04-07
op
blocks.
070
2022-04-07
op
However, defining all the
071
2022-04-07
op
.Ic server
072
2022-04-07
op
blocks after the macros and the global options is recommended.
073
2022-04-07
op
.Pp
074
2022-04-07
op
Newlines are often optional, except around top-level instructions, and
075
2022-04-07
op
semicolons
076
2022-04-07
op
.Dq \&;
077
2022-04-07
op
can also be optionally used to separate options.
078
2022-04-07
op
.Pp
079
2022-04-07
op
Additional configuration files can be included with the
080
2022-04-07
op
.Ic include
081
2022-04-07
op
keyword, for example:
082
2022-04-07
op
.Bd -literal -offset indent
083
2022-04-07
op
include "/etc/gmid.conf.local"
084
2022-04-07
op
.Ed
085
2022-04-07
op
.Ss Macros
086
2022-04-07
op
Macros can be defined that will later be expanded in context.
087
2022-04-07
op
Macro names must start with a letter, digit or underscore and may
088
2022-04-07
op
contain any of those characters.
089
2022-04-07
op
Macros names may not be reserved words.
090
2022-04-07
op
Macros are not expanded inside quotes.
091
2022-04-07
op
.Pp
092
2022-04-07
op
Two kinds of macros are supported: variable-like and proper macros.
093
2022-04-07
op
When a macro is invoked with a
094
2022-04-07
op
.Dq $
095
2022-04-07
op
before its name its expanded as a string, whereas when it's invoked
096
2022-04-07
op
with a
097
2022-04-07
op
.Dq @
098
2022-04-07
op
its expanded in-place.
099
2022-04-07
op
.Pp
100
2022-04-07
op
For example:
101
2022-04-07
op
.Bd -literal -offset indent
102
2022-04-07
op
dir = "/var/gemini"
103
2022-04-07
op
certdir = "/etc/keys"
104
2022-04-07
op
common = "lang it; auto index on"
105
2022-04-07
op
106
2022-04-07
op
server "foo" {
107
2022-04-07
op
root $dir "/foo" # -> /var/gemini/foo
108
2022-04-07
op
cert $certdir "/foo.pem" # -> /etc/keys/foo.pem
109
2022-04-07
op
key $certdir "/foo.key" # -> /etc/keys/foo.key
110
2022-04-07
op
@common
111
2022-04-07
op
}
112
2022-04-07
op
.Ed
113
2022-04-07
op
.Ss Global Options
114
2022-04-07
op
.Bl -tag -width 12m
115
2022-04-07
op
.It Ic chroot Ar path
116
2022-04-07
op
.Xr chroot 2
117
2022-04-07
op
the process to the given
118
2022-04-07
op
.Ar path .
119
2022-04-07
op
The daemon has to be run with root privileges and thus the option
120
2022-04-07
op
.Ic user
121
2022-04-07
op
needs to be provided, so privileges can be dropped.
122
2022-04-07
op
Note that
123
2022-04-07
op
.Nm
124
2022-04-07
op
will enter the chroot after loading the TLS keys, but before opening
125
2022-04-07
op
the virtual host root directories.
126
2022-04-07
op
It's recommended to keep the TLS keys outside the chroot.
127
2022-04-07
op
Future version of
128
2022-04-07
op
.Nm
129
2022-04-07
op
may enforce this.
130
2022-04-07
op
.It Ic ipv6 Ar bool
131
2022-04-07
op
Enable or disable IPv6 support, off by default.
132
2022-04-07
op
.It Ic port Ar portno
133
2022-04-07
op
The port to listen on.
134
2022-04-07
op
1965 by default.
135
2022-04-07
op
.It Ic prefork Ar number
136
2022-04-07
op
Run the specified number of server processes.
137
2022-04-07
op
This increases the performance and prevents delays when connecting to
138
2022-04-07
op
a server.
139
2022-04-07
op
When not in config-less mode,
140
2022-04-07
op
.Nm
141
2022-04-07
op
runs 3 server processes by default.
142
2022-04-07
op
The maximum number allowed is 16.
143
2022-04-07
op
.It Ic protocols Ar string
144
2022-04-07
op
Specify the TLS protocols to enable.
145
2022-04-07
op
Refer to
146
2022-04-07
op
.Xr tls_config_parse_protocols 3
147
2022-04-07
op
for the valid protocol string values.
148
2022-04-07
op
By default, both TLSv1.3 and TLSv1.2 are enabled.
149
2022-04-07
op
Use
150
2022-04-07
op
.Dq tlsv1.3
151
2022-04-07
op
to enable only TLSv1.3.
152
2022-04-07
op
.It Ic user Ar string
153
2022-04-07
op
Run the daemon as the given user.
154
2022-04-07
op
.El
155
2022-04-07
op
.Ss Servers
156
2022-04-07
op
Every virtual host is defined by a
157
2022-04-07
op
.Ic server
158
2022-04-07
op
block:
159
2022-04-07
op
.Bl -tag -width Ds
160
2022-04-07
op
.It Ic server Ar hostname Brq ...
161
2022-04-07
op
Match the server name using shell globbing rules.
162
2022-04-07
op
It can be an explicit name,
163
2022-04-07
op
.Ar www.example.com ,
164
2022-04-07
op
or a name including a wildcards,
165
2022-04-07
op
.Ar *.example.com .
166
2022-04-07
op
.El
167
2022-04-07
op
.Pp
168
2022-04-07
op
Followed by a block of options that is enclosed in curly brackets:
169
2022-04-07
op
.Bl -tag -width Ds
170
2022-04-07
op
.It Ic alias Ar name
171
2022-04-07
op
Specify an additional alias
172
2022-04-07
op
.Ar name
173
2022-04-07
op
for this server.
174
2022-04-07
op
.It Ic auto Ic index Ar bool
175
2022-04-07
op
If no index file is found, automatically generate a directory listing.
176
2022-04-07
op
Disabled by default.
177
2022-04-07
op
.It Ic block Op Ic return Ar code Op Ar meta
178
2022-04-07
op
Send a reply and close the connection;
179
2022-04-07
op
by default
180
2022-04-07
op
.Ar code
181
2022-04-07
op
is 40
182
2022-04-07
op
and
183
2022-04-07
op
.Ar meta
184
2022-04-07
op
is
185
2022-04-07
op
.Dq temporary failure .
186
2022-04-07
op
If
187
2022-04-07
op
.Ar code
188
2022-04-07
op
is in the 3x range, then
189
2022-04-07
op
.Ar meta
190
2022-04-07
op
is mandatory.
191
2022-04-07
op
Inside
192
2022-04-07
op
.Ar meta ,
193
2022-04-07
op
the following special sequences are supported:
194
2022-04-07
op
.Bl -tag -width Ds -compact
195
2022-04-07
op
.It \&%\&%
196
2022-04-07
op
is replaced with a single
197
2022-04-07
op
.Sq \&% .
198
2022-04-07
op
.It \&%p
199
2022-04-07
op
is replaced with the request path.
200
2022-04-07
op
.It \&%q
201
2022-04-07
op
is replaced with the query string of the request.
202
2022-04-07
op
.It \&%P
203
2022-04-07
op
is replaced with the server port.
204
2022-04-07
op
.It \&%N
205
2022-04-07
op
is replaced with the server name.
206
2022-04-07
op
.El
207
2022-04-07
op
.It Ic cert Ar file
208
2022-04-07
op
Path to the certificate to use for this server.
209
2022-04-07
op
.Ar file
210
2022-04-07
op
should contain a PEM encoded certificate.
211
2022-04-07
op
This option is mandatory.
212
2022-04-07
op
.It Ic cgi Ar path
213
2022-04-07
op
Execute
214
2022-04-07
op
.Sx CGI
215
2022-04-07
op
scripts that matches
216
2022-04-07
op
.Ar path
217
2022-04-07
op
using shell globbing rules.
218
2022-04-07
op
.Pp
219
2022-04-07
op
The CGI scripts are executed in the directory they reside and inherit
220
2022-04-07
op
the environment from
221
2022-04-07
op
.Nm gmid
222
2022-04-07
op
with these additional variables set:
223
2022-04-07
op
.Bl -tag -width 24m
224
2022-04-07
op
.It Ev GATEWAY_INTERFACE
225
2022-04-07
op
.Dq CGI/1.1
226
2022-04-07
op
.It Ev GEMINI_DOCUMENT_ROOT
227
2022-04-07
op
The root directory of the virtual host.
228
2022-04-07
op
.It Ev GEMINI_SCRIPT_FILENAME
229
2022-04-07
op
Full path to the CGI script being executed.
230
2022-04-07
op
.It Ev GEMINI_URL
231
2022-04-07
op
The full IRI of the request.
232
2022-04-07
op
.It Ev GEMINI_URL_PATH
233
2022-04-07
op
The path of the request.
234
2022-04-07
op
.It Ev PATH_INFO
235
2022-04-07
op
The portion of the requested path that is derived from the the IRI
236
2022-04-07
op
path hierarchy following the part that identifies the script itself.
237
2022-04-07
op
Can be unset.
238
2022-04-07
op
.It Ev PATH_TRANSLATED
239
2022-04-07
op
Present if and only if
240
2022-04-07
op
.Ev PATH_INFO
241
2022-04-07
op
is set.
242
2022-04-07
op
It represent the translation of the
243
2022-04-07
op
.Ev PATH_INFO .
244
2022-04-07
op
.Nm gmid
245
2022-04-07
op
builds this by appending the
246
2022-04-07
op
.Ev PATH_INFO
247
2022-04-07
op
to the virtual host directory root.
248
2022-04-07
op
.It Ev QUERY_STRING
249
2022-04-07
op
The decoded query string.
250
2022-04-07
op
.It Ev REMOTE_ADDR , Ev REMOTE_HOST
251
2022-04-07
op
Textual representation of the client IP.
252
2022-04-07
op
.It Ev REQUEST_METHOD
253
2022-04-07
op
This is present only for RFC3875 (CGI) compliance.
254
2022-04-07
op
It's always set to the empty string.
255
2022-04-07
op
.It Ev SCRIPT_NAME
256
2022-04-07
op
The part of the
257
2022-04-07
op
.Ev GEMINI_URL_PATH
258
2022-04-07
op
that identifies the current CGI script.
259
2022-04-07
op
.It Ev SERVER_NAME
260
2022-04-07
op
The name of the server
261
2022-04-07
op
.It Ev SERVER_PORT
262
2022-04-07
op
The port the server is listening on.
263
2022-04-07
op
.It Ev SERVER_PROTOCOL
264
2022-04-07
op
.Dq GEMINI
265
2022-04-07
op
.It Ev SERVER_SOFTWARE
266
2022-04-07
op
The name and version of the server, i.e.
267
2022-07-04
op
.Dq gmid/1.8.4
268
2022-04-07
op
.It Ev AUTH_TYPE
269
2022-04-07
op
The string "Certificate" if the client used a certificate, otherwise
270
2022-04-07
op
unset.
271
2022-04-07
op
.It Ev REMOTE_USER
272
2022-04-07
op
The subject of the client certificate if provided, otherwise unset.
273
2022-04-07
op
.It Ev TLS_CLIENT_ISSUER
274
2022-04-07
op
The is the issuer of the client certificate if provided, otherwise
275
2022-04-07
op
unset.
276
2022-04-07
op
.It Ev TLS_CLIENT_HASH
277
2022-04-07
op
The hash of the client certificate if provided, otherwise unset.
278
2022-04-07
op
The format is
279
2022-04-07
op
.Dq ALGO:HASH .
280
2022-04-07
op
.It Ev TLS_VERSION
281
2022-04-07
op
The TLS version negotiated with the peer.
282
2022-04-07
op
.It Ev TLS_CIPHER
283
2022-04-07
op
The cipher suite negotiated with the peer.
284
2022-04-07
op
.It Ev TLS_CIPHER_STRENGTH
285
2022-04-07
op
The strength in bits for the symmetric cipher that is being used with
286
2022-04-07
op
the peer.
287
2022-04-07
op
.It Ev TLS_CLIENT_NOT_AFTER
288
2022-04-07
op
The time corresponding to the end of the validity period of the peer
289
2022-04-07
op
certificate in the ISO 8601 format
290
2022-04-07
op
.Pq e.g. Dq 2021-02-07T20:17:41Z .
291
2022-04-07
op
.It Ev TLS_CLIENT_NOT_BEFORE
292
2022-04-07
op
The time corresponding to the start of the validity period of the peer
293
2022-04-07
op
certificate in the ISO 8601 format.
294
2022-04-07
op
.El
295
2022-04-07
op
.It Ic default type Ar string
296
2022-04-07
op
Set the default media type that is used if the media type for a
297
2022-04-07
op
specified extension is not found.
298
2022-04-07
op
If not specified, the
299
2022-04-07
op
.Ic default type
300
2022-04-07
op
is set to
301
2022-04-07
op
.Dq application/octet-stream .
302
2022-04-07
op
.It Ic entrypoint Ar path
303
2022-04-07
op
Handle all the requests for the current virtual host using the
304
2022-04-07
op
.Sx CGI
305
2022-04-07
op
script at
306
2022-04-07
op
.Ar path ,
307
2022-04-07
op
relative to the current document root.
308
2022-04-07
op
.It Ic env Ar name Cm = Ar value
309
2022-04-07
op
Set the environment variable
310
2022-04-07
op
.Ar name
311
2022-04-07
op
to
312
2022-04-07
op
.Ar value
313
2022-04-07
op
when executing CGI scripts.
314
2022-04-07
op
Can be provided more than once.
315
2022-04-07
op
.\" don't document the "spawn <prog>" form because it probably won't
316
2022-04-07
op
.\" be kept.
317
2022-04-07
op
.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
318
2022-04-07
op
Enable
319
2022-04-07
op
.Sx FastCGI
320
2022-04-07
op
instead of serving files.
321
2022-04-07
op
The
322
2022-04-07
op
.Ar socket
323
2022-04-07
op
can either be a UNIX-domain socket or a TCP socket.
324
2022-04-07
op
If the FastCGI application is listening on a UNIX domain socket,
325
2022-04-07
op
.Ar socket
326
2022-04-07
op
is a local path name within the
327
2022-04-07
op
.Xr chroot 2
328
2022-04-07
op
root directory of
329
2022-04-07
op
.Nm .
330
2022-04-07
op
Otherwise, the
331
2022-04-07
op
.Ic tcp
332
2022-04-07
op
keyword must be provided and
333
2022-04-07
op
.Ar socket
334
2022-04-07
op
is interpreted as a hostname or an IP address.
335
2022-04-07
op
.Ar port
336
2022-04-07
op
can be either a port number or the name of a service enclosed in
337
2022-04-07
op
double quotes.
338
2022-04-07
op
If not specified defaults to 9000.
339
2022-04-07
op
.It Ic index Ar string
340
2022-04-07
op
Set the directory index file.
341
2022-04-07
op
If not specified, it defaults to
342
2022-04-07
op
.Pa index.gmi .
343
2022-04-07
op
.It Ic key Ar file
344
2022-04-07
op
Specify the private key to use for this server.
345
2022-04-07
op
.Ar file
346
2022-04-07
op
should contain a PEM encoded private key.
347
2022-04-07
op
This option is mandatory.
348
2022-04-07
op
.It Ic lang Ar string
349
2022-04-07
op
Specify the language tag for the text/gemini content served.
350
2022-04-07
op
If not specified, no
351
2022-04-07
op
.Dq lang
352
2022-04-07
op
parameter will be added in the response.
353
2022-04-07
op
.It Ic location Ar path Brq ...
354
2022-04-07
op
Specify server configuration rules for a specific location.
355
2022-04-07
op
.Ar path
356
2022-04-07
op
argument will be matched against the request path with shell globbing
357
2022-04-07
op
rules.
358
2022-04-07
op
In case of multiple location statements in the same context, the first
359
2022-04-07
op
matching location will be put into effect and the later ones ignored.
360
2022-04-07
op
Therefore is advisable to match for more specific paths first and for
361
2022-04-07
op
generic ones later on.
362
2022-04-07
op
A
363
2022-04-07
op
.Ic location
364
2022-04-07
op
section may include most of the server configuration rules
365
2022-04-07
op
except
366
2022-04-07
op
.Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
367
2022-04-07
op
.Ic location , Ic param No and Ic proxy .
368
2022-04-07
op
.It Ic log Ar bool
369
2022-04-07
op
Enable or disable the logging for the current server or location block.
370
2022-04-07
op
.It Ic param Ar name Cm = Ar value
371
2022-04-07
op
Set the param
372
2022-04-07
op
.Ar name
373
2022-04-07
op
to
374
2022-04-07
op
.Ar value
375
2022-04-07
op
for FastCGI.
376
2022-04-07
op
By default the following variables
377
2022-04-07
op
.Pq parameters
378
2022-04-07
op
are sent, and carry the same semantics as with CGI:
379
2022-04-07
op
.Pp
380
2022-04-07
op
.Bl -bullet -compact
381
2022-04-07
op
.It
382
2022-04-07
op
GATEWAY_INTERFACE
383
2022-04-07
op
.It
384
2022-04-07
op
GEMINI_URL_PATH
385
2022-04-07
op
.It
386
2022-04-07
op
QUERY_STRING
387
2022-04-07
op
.It
388
2022-04-07
op
REMOTE_ADDR
389
2022-04-07
op
.It
390
2022-04-07
op
REMOTE_HOST
391
2022-04-07
op
.It
392
2022-04-07
op
REQUEST_METHOD
393
2022-04-07
op
.It
394
2022-04-07
op
SERVER_NAME
395
2022-04-07
op
.It
396
2022-04-07
op
SERVER_PROTOCOL
397
2022-04-07
op
.It
398
2022-04-07
op
SERVER_SOFTWARE
399
2022-04-07
op
.It
400
2022-04-07
op
AUTH_TYPE
401
2022-04-07
op
.It
402
2022-04-07
op
REMOTE_USER
403
2022-04-07
op
.It
404
2022-04-07
op
TLS_CLIENT_ISSUER
405
2022-04-07
op
.It
406
2022-04-07
op
TLS_CLIENT_HASH
407
2022-04-07
op
.It
408
2022-04-07
op
TLS_VERSION
409
2022-04-07
op
.It
410
2022-04-07
op
TLS_CIPHER
411
2022-04-07
op
.It
412
2022-04-07
op
TLS_CIPHER_STRENGTH
413
2022-04-07
op
.It
414
2022-04-07
op
TLS_CLIENT_NOT_BEFORE
415
2022-04-07
op
.It
416
2022-04-07
op
TLS_CLIENT_NOT_AFTER
417
2022-04-07
op
.El
418
2022-04-07
op
.It Ic ocsp Ar file
419
2022-04-07
op
Specify an OCSP response to be stapled during TLS handshakes
420
2022-04-07
op
with this server.
421
2022-04-07
op
The
422
2022-04-07
op
.Ar file
423
2022-04-07
op
should contain a DER-format OCSP response retrieved from an
424
2022-04-07
op
OCSP server for the
425
2022-04-07
op
.Ic cert
426
2022-04-07
op
in use.
427
2022-04-07
op
If the OCSP response in
428
2022-04-07
op
.Ar file
429
2022-04-07
op
is empty, OCSP stapling will not be used.
430
2022-04-07
op
The default is to not use OCSP stapling.
431
2022-04-07
op
.It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
432
2022-04-07
op
Set up a reverse proxy.
433
2022-04-07
op
The optional matching rules
434
2022-04-07
op
.Cm proto
435
2022-04-07
op
and
436
2022-04-07
op
.Cm for-host
437
2022-04-07
op
can be used to enable proxying only for protocols matching
438
2022-04-07
op
.Ar name
439
2022-04-07
op
.Po Dq gemini
440
2022-04-07
op
by default
441
2022-04-07
op
.Pc
442
2022-04-07
op
and/or whose request IRI matches
443
2022-04-07
op
.Ar host
444
2022-04-07
op
and
445
2022-04-07
op
.Ar port
446
2022-04-07
op
.Pq 1965 by default .
447
2022-04-07
op
Matching happens using shell globbing rules.
448
2022-04-07
op
.Pp
449
2022-04-07
op
In case of multiple matching proxy blocks in the same context, the
450
2022-04-07
op
first matching proxy will be put into effect and the later ones
451
2022-04-07
op
ignored.
452
2022-04-07
op
.Pp
453
2022-04-07
op
Valid options are:
454
2022-04-07
op
.Bl -tag -width Ds
455
2022-04-07
op
.It Ic cert Ar file
456
2022-04-07
op
Specify the client certificate to use when making requests.
457
2022-04-07
op
.It Ic key Ar file
458
2022-04-07
op
Specify the client certificate key to use when making requests.
459
2022-04-07
op
.It Ic protocols Ar string
460
2022-04-07
op
Specify the TLS protocols allowed when making remote requests.
461
2022-04-07
op
Refer to the
462
2022-04-07
op
.Xr tls_config_parse_protocols 3
463
2022-04-07
op
function for the valid protocol string values.
464
2022-04-07
op
By default, both TLSv1.2 and TLSv1.3 are enabled.
465
2022-04-07
op
.It Ic relay-to Ar host : Ns Op Ar port
466
2022-04-07
op
Relay the request to the given
467
2022-04-07
op
.Ar host
468
2022-04-07
op
at the given
469
2022-04-07
op
.Ar port ,
470
2022-04-07
op
1965 by default.
471
2022-04-07
op
This is the only mandatory option in a
472
2022-04-07
op
.Ic proxy
473
2022-04-07
op
block.
474
2022-04-07
op
.It Ic require Ic client Ic ca Ar file
475
2022-04-07
op
Allow the proxying only from clients that provide a certificate
476
2022-04-07
op
signed by the CA certificate in
477
2022-04-07
op
.Ar file .
478
2022-04-07
op
.It Ic sni Ar hostname
479
2022-04-07
op
Use the given
480
2022-04-07
op
.Ar hostname
481
2022-04-07
op
instead of the one extracted from the
482
2022-04-07
op
.Ic relay-to
483
2022-04-07
op
rule for the TLS handshake with the proxied gemini server.
484
2022-04-07
op
.It Ic use-tls Ar bool
485
2022-04-07
op
Specify whether to use TLS when connecting to the proxied host.
486
2022-04-07
op
Enabled by default.
487
2022-04-07
op
.It Ic verifyname Ar bool
488
2022-04-07
op
Enable or disable the TLS server name verification.
489
2022-04-07
op
Enabled by default.
490
2022-04-07
op
.El
491
2022-04-07
op
.It Ic root Ar directory
492
2022-04-07
op
Specify the root directory for this server
493
2022-04-07
op
.Pq alas the current Dq document root .
494
2022-04-07
op
It's relative to the chroot if enabled.
495
2022-04-07
op
.It Ic require Ic client Ic ca Ar path
496
2022-04-07
op
Allow requests only from clients that provide a certificate signed by
497
2022-04-07
op
the CA certificate in
498
2022-04-07
op
.Ar path .
499
2022-04-07
op
It needs to be a PEM-encoded certificate and it's not relative to the
500
2022-04-07
op
chroot.
501
2022-04-07
op
.It Ic strip Ar number
502
2022-04-07
op
Strip
503
2022-04-07
op
.Ar number
504
2022-04-07
op
components from the beginning of the path before doing a lookup in the
505
2022-04-07
op
root directory.
506
2022-04-07
op
It's also considered for the
507
2022-04-07
op
.Ar meta
508
2022-04-07
op
parameter in the scope of a
509
2022-04-07
op
.Ic block return .
510
2022-04-07
op
.El
511
2022-04-07
op
.Ss Types
512
2022-04-07
op
The
513
2022-04-07
op
.Ic types
514
2022-04-07
op
section must include one or more lines of the following syntax, enclosed
515
2022-04-07
op
in curly brances:
516
2022-04-07
op
.Bl -tag -width Ds
517
2022-04-07
op
.It Ar type/subtype Ar name Op Ar name ...
518
2022-04-07
op
Set the media
519
2022-04-07
op
.Ar type
520
2022-04-07
op
and
521
2022-04-07
op
.Ar subtype
522
2022-04-07
op
to the specified extension
523
2022-04-07
op
.Ar name .
524
2022-04-07
op
One or more names can be specified per line.
525
2022-04-07
op
Earch line may end with an optional semicolon.
526
2022-04-07
op
.It Ic include Ar file
527
2022-04-07
op
Include types definition from an external file, for example
528
2022-04-07
op
.Pa /usr/share/misc/mime.types .
529
2022-04-07
op
.El
530
2022-04-07
op
.Pp
531
2022-04-07
op
By default
532
2022-04-07
op
.Nm gmid
533
2022-04-08
op
uses the following mapping if no
534
2022-04-08
op
.Ic types
535
2022-04-08
op
block is defined:
536
2022-04-07
op
.Bl -tag -offset indent -width 15m -compact
537
2022-04-07
op
.It application/pdf
538
2022-04-07
op
pdf
539
2022-04-07
op
.It image/gif
540
2022-04-07
op
gif
541
2022-04-07
op
.It image/jpeg
542
2022-04-08
op
jpg jpeg
543
2022-04-07
op
.It image/png
544
2022-04-07
op
png
545
2022-04-07
op
.It image/svg+xml
546
2022-04-07
op
svg
547
2022-04-07
op
.It text/gemini
548
2022-04-07
op
gemini gmi
549
2022-04-07
op
.It text/markdown
550
2022-04-07
op
markdown md
551
2022-04-07
op
.It text/x-patch
552
2022-04-07
op
diff patch
553
2022-04-07
op
.It text/xml
554
2022-04-07
op
xml
555
2022-04-07
op
.El
556
2022-04-08
op
.Pp
557
2022-04-08
op
As an exception,
558
2022-04-08
op
.Nm gmid
559
2022-04-08
op
uses the MIME type
560
2022-04-08
op
.Ar text/gemini
561
2022-04-08
op
for file extensions
562
2022-04-08
op
.Ar gemini
563
2022-04-08
op
or
564
2022-04-08
op
.Ar gmi
565
2022-04-08
op
if no mapping was found.
566
2022-04-07
op
.Sh EXAMPLES
567
2022-04-07
op
The following is an example of a possible configuration for a site
568
2022-04-07
op
that enables only TLSv1.3, adds the MIME types mapping from
569
2022-04-07
op
.Pa /usr/share/misc/mime.types
570
2022-04-07
op
and defines two virtual host:
571
2022-04-07
op
.Bd -literal -offset indent
572
2022-04-07
op
ipv6 on # enable ipv6
573
2022-04-07
op
574
2022-04-07
op
protocols "tlsv1.3"
575
2022-04-07
op
576
2022-04-07
op
types {
577
2022-04-07
op
include "/usr/share/misc/mime.types"
578
2022-04-07
op
}
579
2022-04-07
op
580
2022-04-07
op
server "example.com" {
581
2022-04-07
op
cert "/etc/ssl/example.com.pem"
582
2022-04-07
op
key "/etc/ssl/private/example.com.key"
583
2022-04-07
op
root "/var/gemini/example.com"
584
2022-04-07
op
}
585
2022-04-07
op
586
2022-04-07
op
server "example.it" {
587
2022-04-07
op
cert "/etc/ssl/example.it.pem"
588
2022-04-07
op
key "/etc/ssl/private/example.it.key"
589
2022-04-07
op
root "/var/gemini/example.it"
590
2022-04-07
op
591
2022-04-07
op
# execute cgi scripts inside "cgi-bin"
592
2022-04-07
op
cgi "/cgi-bin/*"
593
2022-04-07
op
594
2022-04-07
op
# set the language for text/gemini files
595
2022-04-07
op
lang "it"
596
2022-04-07
op
}
597
2022-04-07
op
.Ed
598
2022-04-07
op
.Pp
599
2022-04-07
op
Yet another example, showing how to enable a
600
2022-04-07
op
.Ic chroot
601
2022-04-07
op
and use
602
2022-04-07
op
.Ic location
603
2022-04-07
op
rule
604
2022-04-07
op
.Bd -literal -offset indent
605
2022-04-07
op
chroot "/var/gemini"
606
2022-04-07
op
user "_gmid"
607
2022-04-07
op
608
2022-04-07
op
server "example.com" {
609
2022-04-07
op
# absolute paths:
610
2022-04-07
op
cert "/etc/ssl/example.com.pem"
611
2022-04-07
op
key "/etc/ssl/private/example.com.key"
612
2022-04-07
op
613
2022-04-07
op
# relative to the chroot:
614
2022-04-07
op
root "/example.com"
615
2022-04-07
op
616
2022-04-07
op
location "/static/*" {
617
2022-04-07
op
# load the following rules only for
618
2022-04-07
op
# requests that matches "/static/*"
619
2022-04-07
op
620
2022-04-07
op
auto index on
621
2022-04-07
op
index "index.gemini"
622
2022-04-07
op
}
623
2022-04-07
op
}
624
2022-04-07
op
.Ed
625
2022-04-07
op
.Sh SEE ALSO
626
2022-04-07
op
.Xr gmid 1 ,
627
2022-04-07
op
.Xr slowcgi 8
628
2022-04-07
op
.Sh AUTHORS
629
2022-04-07
op
.An -nosplit
630
2022-04-07
op
The
631
2022-04-07
op
.Nm gmid
632
2022-04-07
op
program was written by
633
2022-04-07
op
.An Omar Polo Aq Mt op@omarpolo.com .
Omar Polo