Blame


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