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