Blame


1 a9092d0e 2024-01-11 op .\" Copyright (c) 2022, 2023, 2024 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 bdfea70f 2024-06-28 op .Dd June 28, 2024
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 Types
35 1595c277 2022-04-07 op Media types and extensions.
36 36b2905a 2023-10-19 op .It Sy Servers
37 36b2905a 2023-10-19 op Virtual hosts definition.
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 547437cc 2023-08-01 op ext_ip = "10.0.0.1"
103 1595c277 2022-04-07 op dir = "/var/gemini"
104 1595c277 2022-04-07 op certdir = "/etc/keys"
105 1595c277 2022-04-07 op common = "lang it; auto index on"
106 1595c277 2022-04-07 op
107 1595c277 2022-04-07 op server "foo" {
108 547437cc 2023-08-01 op listen on $ext_ip
109 7edcf2b3 2023-06-24 op root $dir "/foo" # "/var/gemini/foo"
110 7edcf2b3 2023-06-24 op cert $certdir "/foo.pem" # "/etc/keys/foo.pem"
111 7edcf2b3 2023-06-24 op key $certdir "/foo.key" # "/etc/keys/foo.key"
112 1595c277 2022-04-07 op @common
113 1595c277 2022-04-07 op }
114 1595c277 2022-04-07 op .Ed
115 1595c277 2022-04-07 op .Ss Global Options
116 1595c277 2022-04-07 op .Bl -tag -width 12m
117 1595c277 2022-04-07 op .It Ic chroot Ar path
118 1595c277 2022-04-07 op .Xr chroot 2
119 1595c277 2022-04-07 op the process to the given
120 1595c277 2022-04-07 op .Ar path .
121 1595c277 2022-04-07 op The daemon has to be run with root privileges and thus the option
122 1595c277 2022-04-07 op .Ic user
123 7edcf2b3 2023-06-24 op needs to be provided too, so privileges can be dropped afterwards.
124 0ed763b0 2024-03-03 op All the paths in the configuration file are relative to the chroot
125 0ed763b0 2024-03-03 op directory, except for the
126 7edcf2b3 2023-06-24 op .Ic cert ,
127 0ed763b0 2024-03-03 op .Ic key
128 9f1cce3d 2024-03-03 op and
129 0ed763b0 2024-03-03 op .Ic ocsp
130 7edcf2b3 2023-06-24 op paths.
131 287ab865 2023-06-24 op Defaults to the
132 287ab865 2023-06-24 op .Ic user
133 287ab865 2023-06-24 op home directory, if provided.
134 226f13ec 2023-07-24 op .It Ic log Ar options
135 226f13ec 2023-07-24 op Specify logging options.
136 226f13ec 2023-07-24 op Multiple options may be provided within curly braces.
137 226f13ec 2023-07-24 op The available options are as follows:
138 226f13ec 2023-07-24 op .Bl -tag -width Ds
139 226f13ec 2023-07-24 op .It Ic access Ar file
140 226f13ec 2023-07-24 op Log the requests to
141 226f13ec 2023-07-24 op .Ar file .
142 0ed763b0 2024-03-03 op The path is relative to the
143 4acf495f 2023-07-24 op .Ic chroot .
144 abd261d2 2023-07-25 op .It Ic style Ar style
145 abd261d2 2023-07-25 op Set the logging style, defaults to
146 f23b7087 2023-08-04 op .Ic legacy .
147 abd261d2 2023-07-25 op The
148 abd261d2 2023-07-25 op .Ar style
149 abd261d2 2023-07-25 op can be one of:
150 abd261d2 2023-07-25 op .Bl -tag -width Ds
151 abd261d2 2023-07-25 op .It Ic common
152 abd261d2 2023-07-25 op Attempt to be compatible with the default Apache httpd log format.
153 abd261d2 2023-07-25 op Each line is formatted as follows: the matching host name,
154 abd261d2 2023-07-25 op the remote IP address, one dash
155 abd261d2 2023-07-25 op .Sq - ,
156 abd261d2 2023-07-25 op Common Name of the client certificate
157 abd261d2 2023-07-25 op .Pq if provided, '-' otherwise ,
158 abd261d2 2023-07-25 op the timestamp of the request, the request URI wrapped in double quotes,
159 abd261d2 2023-07-25 op the response code and the size of the response.
160 abd261d2 2023-07-25 op .It Ic combined
161 abd261d2 2023-07-25 op Attempt to be compatible with the default nginx log format.
162 abd261d2 2023-07-25 op Each line is formatted as follows: the remote IP address, one dash
163 abd261d2 2023-07-25 op .Sq - ,
164 abd261d2 2023-07-25 op Common Name of the client certificate
165 abd261d2 2023-07-25 op .Pq if provided, '-' otherwise ,
166 abd261d2 2023-07-25 op the timestamp wrapped in square brackets, the request URI wrapped in
167 abd261d2 2023-07-25 op double quotes, the response code, the size of the response, a dash
168 abd261d2 2023-07-25 op wrapped in double quotes and "".
169 abd261d2 2023-07-25 op The strangness of these two last fields is because Gemini doesn't have
170 abd261d2 2023-07-25 op the notion of the
171 abd261d2 2023-07-25 op .Dq Referer
172 abd261d2 2023-07-25 op header nor the
173 abd261d2 2023-07-25 op .Dq User-agent .
174 a250aff2 2023-08-04 op .\" .It Ic condensed
175 a250aff2 2023-08-04 op .\" The native
176 a250aff2 2023-08-04 op .\" .Xr gmid 8
177 a250aff2 2023-08-04 op .\" format since 2.0.
178 a250aff2 2023-08-04 op .\" Each line is formatted as follows: RFC 3339 date time,
179 a250aff2 2023-08-04 op .\" remote IP address, Common Name of the client certificate
180 a250aff2 2023-08-04 op .\" .Pq if provided, '-' otherwise ,
181 a250aff2 2023-08-04 op .\" the matching host name, the request URI, the size of the request,
182 a250aff2 2023-08-04 op .\" the size of the response, the response code and meta.
183 abd261d2 2023-07-25 op .It Ic legacy
184 abd261d2 2023-07-25 op Each line is formatted as follows: the remote IP address and port, the
185 abd261d2 2023-07-25 op .Sq GET
186 abd261d2 2023-07-25 op keyword, the request URI, the response code and meta.
187 226f13ec 2023-07-24 op .El
188 0c39da51 2023-07-26 op .It Ic syslog Op Ic off
189 0c39da51 2023-07-26 op Log to syslog.
190 0c39da51 2023-07-26 op It is enabled by default, use the
191 0c39da51 2023-07-26 op .Ic off
192 0c39da51 2023-07-26 op argument to disable.
193 9abba172 2023-08-07 op .It Ic syslog facility Ar facility
194 9abba172 2023-08-07 op Log to
195 9abba172 2023-08-07 op .Xr syslog 3
196 9abba172 2023-08-07 op using specified
197 9abba172 2023-08-07 op .Ar facility .
198 9abba172 2023-08-07 op Available facilities are as follows: daemon, ftp, local0 through local7 and
199 9abba172 2023-08-07 op user.
200 9abba172 2023-08-07 op These are case insensitive and can be prefixed with
201 9abba172 2023-08-07 op .Sq LOG_ .
202 9abba172 2023-08-07 op Not all level may be available on all operating systems.
203 9abba172 2023-08-07 op The default facility is
204 9abba172 2023-08-07 op .Ev LOG_DAEMON .
205 abd261d2 2023-07-25 op .El
206 1595c277 2022-04-07 op .It Ic prefork Ar number
207 1595c277 2022-04-07 op Run the specified number of server processes.
208 1595c277 2022-04-07 op This increases the performance and prevents delays when connecting to
209 1595c277 2022-04-07 op a server.
210 7edcf2b3 2023-06-24 op .Xr gmid 8
211 1595c277 2022-04-07 op runs 3 server processes by default.
212 1595c277 2022-04-07 op The maximum number allowed is 16.
213 1595c277 2022-04-07 op .It Ic protocols Ar string
214 1595c277 2022-04-07 op Specify the TLS protocols to enable.
215 1595c277 2022-04-07 op Refer to
216 1595c277 2022-04-07 op .Xr tls_config_parse_protocols 3
217 1595c277 2022-04-07 op for the valid protocol string values.
218 1595c277 2022-04-07 op By default, both TLSv1.3 and TLSv1.2 are enabled.
219 1595c277 2022-04-07 op Use
220 1595c277 2022-04-07 op .Dq tlsv1.3
221 1595c277 2022-04-07 op to enable only TLSv1.3.
222 1595c277 2022-04-07 op .It Ic user Ar string
223 1595c277 2022-04-07 op Run the daemon as the given user.
224 2c079c9e 2023-08-01 op Mandatory if the
225 2c079c9e 2023-08-01 op .Ic chroot
226 2c079c9e 2023-08-01 op option is used.
227 1595c277 2022-04-07 op .El
228 1595c277 2022-04-07 op .Ss Servers
229 1595c277 2022-04-07 op Every virtual host is defined by a
230 1595c277 2022-04-07 op .Ic server
231 1595c277 2022-04-07 op block:
232 1595c277 2022-04-07 op .Bl -tag -width Ds
233 1595c277 2022-04-07 op .It Ic server Ar hostname Brq ...
234 1595c277 2022-04-07 op Match the server name using shell globbing rules.
235 1595c277 2022-04-07 op It can be an explicit name,
236 1595c277 2022-04-07 op .Ar www.example.com ,
237 5bee9bd7 2023-10-20 op or a name including wildcards,
238 1595c277 2022-04-07 op .Ar *.example.com .
239 1595c277 2022-04-07 op .El
240 1595c277 2022-04-07 op .Pp
241 1595c277 2022-04-07 op Followed by a block of options that is enclosed in curly brackets:
242 1595c277 2022-04-07 op .Bl -tag -width Ds
243 1595c277 2022-04-07 op .It Ic alias Ar name
244 1595c277 2022-04-07 op Specify an additional alias
245 1595c277 2022-04-07 op .Ar name
246 1595c277 2022-04-07 op for this server.
247 1595c277 2022-04-07 op .It Ic auto Ic index Ar bool
248 1595c277 2022-04-07 op If no index file is found, automatically generate a directory listing.
249 1595c277 2022-04-07 op Disabled by default.
250 1595c277 2022-04-07 op .It Ic block Op Ic return Ar code Op Ar meta
251 1595c277 2022-04-07 op Send a reply and close the connection;
252 1595c277 2022-04-07 op by default
253 1595c277 2022-04-07 op .Ar code
254 1595c277 2022-04-07 op is 40
255 1595c277 2022-04-07 op and
256 1595c277 2022-04-07 op .Ar meta
257 1595c277 2022-04-07 op is
258 1595c277 2022-04-07 op .Dq temporary failure .
259 1595c277 2022-04-07 op If
260 1595c277 2022-04-07 op .Ar code
261 1595c277 2022-04-07 op is in the 3x range, then
262 1595c277 2022-04-07 op .Ar meta
263 1595c277 2022-04-07 op is mandatory.
264 1595c277 2022-04-07 op Inside
265 1595c277 2022-04-07 op .Ar meta ,
266 1595c277 2022-04-07 op the following special sequences are supported:
267 1595c277 2022-04-07 op .Bl -tag -width Ds -compact
268 1595c277 2022-04-07 op .It \&%\&%
269 1595c277 2022-04-07 op is replaced with a single
270 1595c277 2022-04-07 op .Sq \&% .
271 1595c277 2022-04-07 op .It \&%p
272 1595c277 2022-04-07 op is replaced with the request path.
273 1595c277 2022-04-07 op .It \&%q
274 1595c277 2022-04-07 op is replaced with the query string of the request.
275 1595c277 2022-04-07 op .It \&%P
276 1595c277 2022-04-07 op is replaced with the server port.
277 1595c277 2022-04-07 op .It \&%N
278 1595c277 2022-04-07 op is replaced with the server name.
279 1595c277 2022-04-07 op .El
280 1595c277 2022-04-07 op .It Ic cert Ar file
281 1595c277 2022-04-07 op Path to the certificate to use for this server.
282 1595c277 2022-04-07 op .Ar file
283 1595c277 2022-04-07 op should contain a PEM encoded certificate.
284 1595c277 2022-04-07 op This option is mandatory.
285 9b15e4c6 2022-09-08 op .It Ic default type Ar string
286 9b15e4c6 2022-09-08 op Set the default media type that is used if the media type for a
287 9b15e4c6 2022-09-08 op specified extension is not found.
288 9b15e4c6 2022-09-08 op If not specified, the
289 9b15e4c6 2022-09-08 op .Ic default type
290 9b15e4c6 2022-09-08 op is set to
291 9b15e4c6 2022-09-08 op .Dq application/octet-stream .
292 a1ba9650 2023-07-23 op .It Ic fastcgi Ar option
293 a1ba9650 2023-07-23 op Enable FastCGI instead of serving files.
294 a1ba9650 2023-07-23 op Multiple options may be specified within curly braces.
295 a1ba9650 2023-07-23 op Valid options are:
296 a1ba9650 2023-07-23 op .Bl -tag -width Ds
297 a1ba9650 2023-07-23 op .It Ic param Ar name Cm = Ar value
298 a1ba9650 2023-07-23 op Set the param
299 a1ba9650 2023-07-23 op .Ar name
300 a1ba9650 2023-07-23 op to
301 a1ba9650 2023-07-23 op .Ar value .
302 a1ba9650 2023-07-23 op .It Ic socket Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
303 9b15e4c6 2022-09-08 op The
304 9b15e4c6 2022-09-08 op .Ar socket
305 9b15e4c6 2022-09-08 op can either be a UNIX-domain socket or a TCP socket.
306 9b15e4c6 2022-09-08 op If the FastCGI application is listening on a UNIX domain socket,
307 9b15e4c6 2022-09-08 op .Ar socket
308 9b15e4c6 2022-09-08 op is a local path name within the
309 9b15e4c6 2022-09-08 op .Xr chroot 2
310 9b15e4c6 2022-09-08 op root directory of
311 c2bcf6a4 2023-08-03 op .Xr gmid 8 .
312 9b15e4c6 2022-09-08 op Otherwise, the
313 9b15e4c6 2022-09-08 op .Ic tcp
314 9b15e4c6 2022-09-08 op keyword must be provided and
315 9b15e4c6 2022-09-08 op .Ar socket
316 9b15e4c6 2022-09-08 op is interpreted as a hostname or an IP address.
317 9b15e4c6 2022-09-08 op .Ar port
318 9b15e4c6 2022-09-08 op can be either a port number or the name of a service enclosed in
319 9b15e4c6 2022-09-08 op double quotes.
320 9b15e4c6 2022-09-08 op If not specified defaults to 9000.
321 03d671e2 2023-08-08 op .It Ic strip Ar number
322 03d671e2 2023-08-08 op Strip
323 03d671e2 2023-08-08 op .Ar number
324 a9092d0e 2024-01-11 op leading path components from the request URL before splitting it in
325 a9092d0e 2024-01-11 op .Ev SCRIPT_NAME
326 a9092d0e 2024-01-11 op and
327 a9092d0e 2024-01-11 op .Ev PATH_INFO .
328 a1ba9650 2023-07-23 op .El
329 a1ba9650 2023-07-23 op .Pp
330 a1ba9650 2023-07-23 op The FastCGI handler will be given the following variables by default:
331 1595c277 2022-04-07 op .Bl -tag -width 24m
332 e872053b 2023-08-18 op .\" .It Ev GEMINI_DOCUMENT_ROOT
333 e872053b 2023-08-18 op .\" The root directory of the virtual host.
334 1595c277 2022-04-07 op .It Ev GEMINI_URL_PATH
335 e872053b 2023-08-18 op Full path of the request.
336 97b306cb 2022-11-27 op .It Ev GEMINI_SEARCH_STRING
337 97b306cb 2022-11-27 op The decoded
338 97b306cb 2022-11-27 op .Ev QUERY_STRING
339 97b306cb 2022-11-27 op if defined in the request and if it doesn't contain any unencoded
340 97b306cb 2022-11-27 op .Sq =
341 97b306cb 2022-11-27 op characters, otherwise unset.
342 e872053b 2023-08-18 op .It Ev GATEWAY_INTERFACE
343 e872053b 2023-08-18 op .Dq CGI/1.1
344 e872053b 2023-08-18 op .It Ev AUTH_TYPE
345 e872053b 2023-08-18 op The string "Certificate" if the client used a certificate, otherwise
346 e872053b 2023-08-18 op unset.
347 1595c277 2022-04-07 op .It Ev PATH_INFO
348 1595c277 2022-04-07 op The portion of the requested path that is derived from the the IRI
349 e872053b 2023-08-18 op path hierarchy following
350 e872053b 2023-08-18 op .Ev SCRIPT_NAME .
351 1595c277 2022-04-07 op Can be unset.
352 1595c277 2022-04-07 op .It Ev PATH_TRANSLATED
353 1595c277 2022-04-07 op Present if and only if
354 1595c277 2022-04-07 op .Ev PATH_INFO
355 1595c277 2022-04-07 op is set.
356 1595c277 2022-04-07 op It represent the translation of the
357 1595c277 2022-04-07 op .Ev PATH_INFO .
358 1595c277 2022-04-07 op .Nm gmid
359 1595c277 2022-04-07 op builds this by appending the
360 1595c277 2022-04-07 op .Ev PATH_INFO
361 1595c277 2022-04-07 op to the virtual host directory root.
362 1595c277 2022-04-07 op .It Ev QUERY_STRING
363 77718c12 2022-11-27 op The URL-encoded search or parameter string.
364 1595c277 2022-04-07 op .It Ev REMOTE_ADDR , Ev REMOTE_HOST
365 1595c277 2022-04-07 op Textual representation of the client IP.
366 1595c277 2022-04-07 op .It Ev REQUEST_METHOD
367 1595c277 2022-04-07 op This is present only for RFC3875 (CGI) compliance.
368 e872053b 2023-08-18 op It's always set to
369 e872053b 2023-08-18 op .Dq GET .
370 1595c277 2022-04-07 op .It Ev SCRIPT_NAME
371 9b15e4c6 2022-09-08 op The virtual URI path to the script.
372 e872053b 2023-08-18 op Since it's impossible to determine in all cases the correct
373 e872053b 2023-08-18 op .Ev SCRIPT_NAME
374 e872053b 2023-08-18 op programmatically
375 e872053b 2023-08-18 op .Nm gmid
376 e872053b 2023-08-18 op assumes it's the empty string.
377 e872053b 2023-08-18 op It is recommended to manually specify this parameter when serving a
378 e872053b 2023-08-18 op sub-tree of a virtual host via FastCGI.
379 1595c277 2022-04-07 op .It Ev SERVER_NAME
380 1595c277 2022-04-07 op The name of the server
381 1595c277 2022-04-07 op .It Ev SERVER_PORT
382 1595c277 2022-04-07 op The port the server is listening on.
383 1595c277 2022-04-07 op .It Ev SERVER_PROTOCOL
384 1595c277 2022-04-07 op .Dq GEMINI
385 1595c277 2022-04-07 op .It Ev SERVER_SOFTWARE
386 1595c277 2022-04-07 op The name and version of the server, i.e.
387 cb384f42 2024-06-11 op .Dq gmid/2.0.5
388 1595c277 2022-04-07 op .It Ev REMOTE_USER
389 1595c277 2022-04-07 op The subject of the client certificate if provided, otherwise unset.
390 1595c277 2022-04-07 op .It Ev TLS_CLIENT_ISSUER
391 1595c277 2022-04-07 op The is the issuer of the client certificate if provided, otherwise
392 1595c277 2022-04-07 op unset.
393 1595c277 2022-04-07 op .It Ev TLS_CLIENT_HASH
394 1595c277 2022-04-07 op The hash of the client certificate if provided, otherwise unset.
395 1595c277 2022-04-07 op The format is
396 1595c277 2022-04-07 op .Dq ALGO:HASH .
397 1595c277 2022-04-07 op .It Ev TLS_VERSION
398 1595c277 2022-04-07 op The TLS version negotiated with the peer.
399 1595c277 2022-04-07 op .It Ev TLS_CIPHER
400 1595c277 2022-04-07 op The cipher suite negotiated with the peer.
401 1595c277 2022-04-07 op .It Ev TLS_CIPHER_STRENGTH
402 1595c277 2022-04-07 op The strength in bits for the symmetric cipher that is being used with
403 1595c277 2022-04-07 op the peer.
404 1595c277 2022-04-07 op .It Ev TLS_CLIENT_NOT_AFTER
405 1595c277 2022-04-07 op The time corresponding to the end of the validity period of the peer
406 1595c277 2022-04-07 op certificate in the ISO 8601 format
407 1595c277 2022-04-07 op .Pq e.g. Dq 2021-02-07T20:17:41Z .
408 1595c277 2022-04-07 op .It Ev TLS_CLIENT_NOT_BEFORE
409 1595c277 2022-04-07 op The time corresponding to the start of the validity period of the peer
410 1595c277 2022-04-07 op certificate in the ISO 8601 format.
411 1595c277 2022-04-07 op .El
412 6a8387e5 2023-07-23 op .It Ic fastcgi off
413 6a8387e5 2023-07-23 op Disable FastCGI handling in the current location.
414 a1ba9650 2023-07-23 op .It Ic index Ar string
415 a1ba9650 2023-07-23 op Set the directory index file.
416 a1ba9650 2023-07-23 op If not specified, it defaults to
417 a1ba9650 2023-07-23 op .Pa index.gmi .
418 a1ba9650 2023-07-23 op .It Ic key Ar file
419 a1ba9650 2023-07-23 op Specify the private key to use for this server.
420 a1ba9650 2023-07-23 op .Ar file
421 a1ba9650 2023-07-23 op should contain a PEM encoded private key.
422 a1ba9650 2023-07-23 op This option is mandatory.
423 a1ba9650 2023-07-23 op .It Ic lang Ar string
424 a1ba9650 2023-07-23 op Specify the language tag for the text/gemini content served.
425 a1ba9650 2023-07-23 op If not specified, no
426 a1ba9650 2023-07-23 op .Dq lang
427 a1ba9650 2023-07-23 op parameter will be added in the response.
428 bdfea70f 2024-06-28 op .It Ic listen on Ar address Oo Ic port Ar number Oc Op Ic proxy-v1
429 a1ba9650 2023-07-23 op Set the listen
430 a1ba9650 2023-07-23 op .Ar address
431 a1ba9650 2023-07-23 op and
432 a1ba9650 2023-07-23 op .Ar port
433 a1ba9650 2023-07-23 op which defaults to
434 a1ba9650 2023-07-23 op .Sq 1965 .
435 a1ba9650 2023-07-23 op This statement can be specified multiple times.
436 a1ba9650 2023-07-23 op If
437 a1ba9650 2023-07-23 op .Ar address
438 a1ba9650 2023-07-23 op is
439 a1ba9650 2023-07-23 op .Sq *
440 a1ba9650 2023-07-23 op then
441 a1ba9650 2023-07-23 op .Xr gmid 8
442 a1ba9650 2023-07-23 op will listen on all IPv4 and IPv6 addresses.
443 a1ba9650 2023-07-23 op .Ar 0.0.0.0
444 a1ba9650 2023-07-23 op can be used to listen on all IPv4 addresses and
445 a1ba9650 2023-07-23 op .Ar ::
446 a1ba9650 2023-07-23 op on all IPv6 addresses.
447 bdfea70f 2024-06-28 op If
448 bdfea70f 2024-06-28 op .Ic proxy-v1
449 bdfea70f 2024-06-28 op is specified, then connections speaking the proxy protocol v1 are
450 bdfea70f 2024-06-28 op expected on this listener.
451 bdfea70f 2024-06-28 op If multiple
452 bdfea70f 2024-06-28 op .Ic listen
453 bdfea70f 2024-06-28 op directive share the same
454 bdfea70f 2024-06-28 op .Ar address
455 bdfea70f 2024-06-28 op and
456 bdfea70f 2024-06-28 op .Ar port ,
457 bdfea70f 2024-06-28 op then all of them must have or lack
458 bdfea70f 2024-06-28 op .Ic proxy-v1 .
459 a1ba9650 2023-07-23 op .It Ic location Ar path Brq ...
460 a1ba9650 2023-07-23 op Specify server configuration rules for a specific location.
461 a1ba9650 2023-07-23 op .Ar path
462 a1ba9650 2023-07-23 op argument will be matched against the request path with shell globbing
463 a1ba9650 2023-07-23 op rules.
464 a1ba9650 2023-07-23 op In case of multiple location statements in the same context, the first
465 a1ba9650 2023-07-23 op matching location will be put into effect and the later ones ignored.
466 a1ba9650 2023-07-23 op Therefore is advisable to match for more specific paths first and for
467 a1ba9650 2023-07-23 op generic ones later on.
468 a1ba9650 2023-07-23 op A
469 a1ba9650 2023-07-23 op .Ic location
470 a1ba9650 2023-07-23 op section may include most of the server configuration rules
471 a1ba9650 2023-07-23 op except
472 a1ba9650 2023-07-23 op .Ic alias , Ic cert , Ic key , Ic listen , Ic location
473 a1ba9650 2023-07-23 op and
474 a1ba9650 2023-07-23 op .Ic proxy .
475 a1ba9650 2023-07-23 op .It Ic log Ar bool
476 a1ba9650 2023-07-23 op Enable or disable the logging for the current server or location block.
477 1595c277 2022-04-07 op .It Ic ocsp Ar file
478 1595c277 2022-04-07 op Specify an OCSP response to be stapled during TLS handshakes
479 1595c277 2022-04-07 op with this server.
480 1595c277 2022-04-07 op The
481 1595c277 2022-04-07 op .Ar file
482 1595c277 2022-04-07 op should contain a DER-format OCSP response retrieved from an
483 1595c277 2022-04-07 op OCSP server for the
484 1595c277 2022-04-07 op .Ic cert
485 1595c277 2022-04-07 op in use.
486 1595c277 2022-04-07 op If the OCSP response in
487 1595c277 2022-04-07 op .Ar file
488 1595c277 2022-04-07 op is empty, OCSP stapling will not be used.
489 1595c277 2022-04-07 op The default is to not use OCSP stapling.
490 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 ...
491 1595c277 2022-04-07 op Set up a reverse proxy.
492 1595c277 2022-04-07 op The optional matching rules
493 1595c277 2022-04-07 op .Cm proto
494 1595c277 2022-04-07 op and
495 1595c277 2022-04-07 op .Cm for-host
496 1595c277 2022-04-07 op can be used to enable proxying only for protocols matching
497 1595c277 2022-04-07 op .Ar name
498 1595c277 2022-04-07 op .Po Dq gemini
499 1595c277 2022-04-07 op by default
500 1595c277 2022-04-07 op .Pc
501 1595c277 2022-04-07 op and/or whose request IRI matches
502 1595c277 2022-04-07 op .Ar host
503 1595c277 2022-04-07 op and
504 1595c277 2022-04-07 op .Ar port
505 1595c277 2022-04-07 op .Pq 1965 by default .
506 1595c277 2022-04-07 op Matching happens using shell globbing rules.
507 1595c277 2022-04-07 op .Pp
508 1595c277 2022-04-07 op In case of multiple matching proxy blocks in the same context, the
509 1595c277 2022-04-07 op first matching proxy will be put into effect and the later ones
510 1595c277 2022-04-07 op ignored.
511 1595c277 2022-04-07 op .Pp
512 1595c277 2022-04-07 op Valid options are:
513 1595c277 2022-04-07 op .Bl -tag -width Ds
514 1595c277 2022-04-07 op .It Ic cert Ar file
515 1595c277 2022-04-07 op Specify the client certificate to use when making requests.
516 1595c277 2022-04-07 op .It Ic key Ar file
517 1595c277 2022-04-07 op Specify the client certificate key to use when making requests.
518 1595c277 2022-04-07 op .It Ic protocols Ar string
519 1595c277 2022-04-07 op Specify the TLS protocols allowed when making remote requests.
520 1595c277 2022-04-07 op Refer to the
521 1595c277 2022-04-07 op .Xr tls_config_parse_protocols 3
522 1595c277 2022-04-07 op function for the valid protocol string values.
523 1595c277 2022-04-07 op By default, both TLSv1.2 and TLSv1.3 are enabled.
524 d2da235a 2022-10-05 op .It Ic relay-to Ar host Op Cm port Ar port
525 1595c277 2022-04-07 op Relay the request to the given
526 1595c277 2022-04-07 op .Ar host
527 1595c277 2022-04-07 op at the given
528 1595c277 2022-04-07 op .Ar port ,
529 1595c277 2022-04-07 op 1965 by default.
530 1595c277 2022-04-07 op This is the only mandatory option in a
531 1595c277 2022-04-07 op .Ic proxy
532 1595c277 2022-04-07 op block.
533 1595c277 2022-04-07 op .It Ic require Ic client Ic ca Ar file
534 1595c277 2022-04-07 op Allow the proxying only from clients that provide a certificate
535 1595c277 2022-04-07 op signed by the CA certificate in
536 1595c277 2022-04-07 op .Ar file .
537 1595c277 2022-04-07 op .It Ic sni Ar hostname
538 1595c277 2022-04-07 op Use the given
539 1595c277 2022-04-07 op .Ar hostname
540 1595c277 2022-04-07 op instead of the one extracted from the
541 1595c277 2022-04-07 op .Ic relay-to
542 1595c277 2022-04-07 op rule for the TLS handshake with the proxied gemini server.
543 1595c277 2022-04-07 op .It Ic use-tls Ar bool
544 1595c277 2022-04-07 op Specify whether to use TLS when connecting to the proxied host.
545 1595c277 2022-04-07 op Enabled by default.
546 1595c277 2022-04-07 op .It Ic verifyname Ar bool
547 1595c277 2022-04-07 op Enable or disable the TLS server name verification.
548 1595c277 2022-04-07 op Enabled by default.
549 1595c277 2022-04-07 op .El
550 1595c277 2022-04-07 op .It Ic root Ar directory
551 1595c277 2022-04-07 op Specify the root directory for this server
552 1595c277 2022-04-07 op .Pq alas the current Dq document root .
553 1595c277 2022-04-07 op It's relative to the chroot if enabled.
554 1595c277 2022-04-07 op .It Ic require Ic client Ic ca Ar path
555 1595c277 2022-04-07 op Allow requests only from clients that provide a certificate signed by
556 1595c277 2022-04-07 op the CA certificate in
557 1595c277 2022-04-07 op .Ar path .
558 1595c277 2022-04-07 op It needs to be a PEM-encoded certificate and it's not relative to the
559 1595c277 2022-04-07 op chroot.
560 1595c277 2022-04-07 op .It Ic strip Ar number
561 1595c277 2022-04-07 op Strip
562 1595c277 2022-04-07 op .Ar number
563 1595c277 2022-04-07 op components from the beginning of the path before doing a lookup in the
564 1595c277 2022-04-07 op root directory.
565 1595c277 2022-04-07 op It's also considered for the
566 1595c277 2022-04-07 op .Ar meta
567 1595c277 2022-04-07 op parameter in the scope of a
568 1595c277 2022-04-07 op .Ic block return .
569 1595c277 2022-04-07 op .El
570 1595c277 2022-04-07 op .Ss Types
571 1595c277 2022-04-07 op The
572 1595c277 2022-04-07 op .Ic types
573 1595c277 2022-04-07 op section must include one or more lines of the following syntax, enclosed
574 1595c277 2022-04-07 op in curly brances:
575 1595c277 2022-04-07 op .Bl -tag -width Ds
576 7edcf2b3 2023-06-24 op .It Ar type Ns / Ns Ar subtype Ar name Op Ar name ...
577 1595c277 2022-04-07 op Set the media
578 1595c277 2022-04-07 op .Ar type
579 1595c277 2022-04-07 op and
580 1595c277 2022-04-07 op .Ar subtype
581 1595c277 2022-04-07 op to the specified extension
582 1595c277 2022-04-07 op .Ar name .
583 1595c277 2022-04-07 op One or more names can be specified per line.
584 1595c277 2022-04-07 op Earch line may end with an optional semicolon.
585 1595c277 2022-04-07 op .It Ic include Ar file
586 1595c277 2022-04-07 op Include types definition from an external file, for example
587 1595c277 2022-04-07 op .Pa /usr/share/misc/mime.types .
588 1595c277 2022-04-07 op .El
589 1595c277 2022-04-07 op .Pp
590 1595c277 2022-04-07 op By default
591 1595c277 2022-04-07 op .Nm gmid
592 5f03bf17 2022-04-08 op uses the following mapping if no
593 5f03bf17 2022-04-08 op .Ic types
594 93cab6dc 2022-04-08 op block is defined:
595 7edcf2b3 2023-06-24 op .Pp
596 1595c277 2022-04-07 op .Bl -tag -offset indent -width 15m -compact
597 1595c277 2022-04-07 op .It application/pdf
598 1595c277 2022-04-07 op pdf
599 1595c277 2022-04-07 op .It image/gif
600 1595c277 2022-04-07 op gif
601 1595c277 2022-04-07 op .It image/jpeg
602 aa6b8cf8 2022-04-08 op jpg jpeg
603 1595c277 2022-04-07 op .It image/png
604 1595c277 2022-04-07 op png
605 1595c277 2022-04-07 op .It image/svg+xml
606 1595c277 2022-04-07 op svg
607 1595c277 2022-04-07 op .It text/gemini
608 1595c277 2022-04-07 op gemini gmi
609 1595c277 2022-04-07 op .It text/markdown
610 1595c277 2022-04-07 op markdown md
611 1595c277 2022-04-07 op .It text/x-patch
612 1595c277 2022-04-07 op diff patch
613 1595c277 2022-04-07 op .It text/xml
614 1595c277 2022-04-07 op xml
615 1595c277 2022-04-07 op .El
616 93cab6dc 2022-04-08 op .Pp
617 93cab6dc 2022-04-08 op As an exception,
618 93cab6dc 2022-04-08 op .Nm gmid
619 93cab6dc 2022-04-08 op uses the MIME type
620 93cab6dc 2022-04-08 op .Ar text/gemini
621 93cab6dc 2022-04-08 op for file extensions
622 93cab6dc 2022-04-08 op .Ar gemini
623 93cab6dc 2022-04-08 op or
624 93cab6dc 2022-04-08 op .Ar gmi
625 93cab6dc 2022-04-08 op if no mapping was found.
626 1595c277 2022-04-07 op .Sh EXAMPLES
627 1595c277 2022-04-07 op The following is an example of a possible configuration for a site
628 1595c277 2022-04-07 op that enables only TLSv1.3, adds the MIME types mapping from
629 1595c277 2022-04-07 op .Pa /usr/share/misc/mime.types
630 1595c277 2022-04-07 op and defines two virtual host:
631 1595c277 2022-04-07 op .Bd -literal -offset indent
632 1595c277 2022-04-07 op protocols "tlsv1.3"
633 1595c277 2022-04-07 op
634 1595c277 2022-04-07 op types {
635 1595c277 2022-04-07 op include "/usr/share/misc/mime.types"
636 1595c277 2022-04-07 op }
637 1595c277 2022-04-07 op
638 1595c277 2022-04-07 op server "example.com" {
639 7edcf2b3 2023-06-24 op listen on * port 1965
640 1595c277 2022-04-07 op cert "/etc/ssl/example.com.pem"
641 1595c277 2022-04-07 op key "/etc/ssl/private/example.com.key"
642 1595c277 2022-04-07 op root "/var/gemini/example.com"
643 1595c277 2022-04-07 op }
644 1595c277 2022-04-07 op
645 1595c277 2022-04-07 op server "example.it" {
646 7edcf2b3 2023-06-24 op listen on * port 1965
647 1595c277 2022-04-07 op cert "/etc/ssl/example.it.pem"
648 1595c277 2022-04-07 op key "/etc/ssl/private/example.it.key"
649 1595c277 2022-04-07 op root "/var/gemini/example.it"
650 1595c277 2022-04-07 op
651 1595c277 2022-04-07 op # set the language for text/gemini files
652 1595c277 2022-04-07 op lang "it"
653 1595c277 2022-04-07 op }
654 1595c277 2022-04-07 op .Ed
655 1595c277 2022-04-07 op .Pp
656 1595c277 2022-04-07 op Yet another example, showing how to enable a
657 1595c277 2022-04-07 op .Ic chroot
658 1595c277 2022-04-07 op and use
659 1595c277 2022-04-07 op .Ic location
660 1595c277 2022-04-07 op rule
661 1595c277 2022-04-07 op .Bd -literal -offset indent
662 1595c277 2022-04-07 op chroot "/var/gemini"
663 1595c277 2022-04-07 op user "_gmid"
664 1595c277 2022-04-07 op
665 1595c277 2022-04-07 op server "example.com" {
666 7edcf2b3 2023-06-24 op listen on * port 1965
667 7edcf2b3 2023-06-24 op
668 1595c277 2022-04-07 op # absolute paths:
669 1595c277 2022-04-07 op cert "/etc/ssl/example.com.pem"
670 1595c277 2022-04-07 op key "/etc/ssl/private/example.com.key"
671 1595c277 2022-04-07 op
672 1595c277 2022-04-07 op # relative to the chroot:
673 1595c277 2022-04-07 op root "/example.com"
674 1595c277 2022-04-07 op
675 1595c277 2022-04-07 op location "/static/*" {
676 1595c277 2022-04-07 op # load the following rules only for
677 1595c277 2022-04-07 op # requests that matches "/static/*"
678 1595c277 2022-04-07 op
679 1595c277 2022-04-07 op auto index on
680 1595c277 2022-04-07 op index "index.gemini"
681 161651fa 2023-08-03 op }
682 161651fa 2023-08-03 op }
683 161651fa 2023-08-03 op .Ed
684 161651fa 2023-08-03 op .Pp
685 161651fa 2023-08-03 op This shows how to set up a reverse proxy: all request for
686 161651fa 2023-08-03 op .Sq example.com
687 161651fa 2023-08-03 op will be forwarded to 10.0.0.6 transparently.
688 161651fa 2023-08-03 op Proxying establish a new TLS connection, so any client-certificates used
689 161651fa 2023-08-03 op to connect to
690 161651fa 2023-08-03 op .Xr gmid 8
691 161651fa 2023-08-03 op cannot be provided to the proxied server as well.
692 161651fa 2023-08-03 op .Bd -literal -offset indent
693 161651fa 2023-08-03 op server "example.com" {
694 161651fa 2023-08-03 op listen on * port 1965
695 161651fa 2023-08-03 op cert "/etc/ssl/example.com.pem"
696 161651fa 2023-08-03 op key "/etc/ssl/private/example.com.key"
697 161651fa 2023-08-03 op proxy {
698 161651fa 2023-08-03 op relay-to 10.0.0.6 port 1965
699 1595c277 2022-04-07 op }
700 1595c277 2022-04-07 op }
701 1595c277 2022-04-07 op .Ed
702 1595c277 2022-04-07 op .Sh SEE ALSO
703 9b15e4c6 2022-09-08 op .Xr gmid 8 ,
704 1595c277 2022-04-07 op .Xr slowcgi 8
705 1595c277 2022-04-07 op .Sh AUTHORS
706 1595c277 2022-04-07 op .An -nosplit
707 1595c277 2022-04-07 op The
708 1595c277 2022-04-07 op .Nm gmid
709 1595c277 2022-04-07 op program was written by
710 1595c277 2022-04-07 op .An Omar Polo Aq Mt op@omarpolo.com .