1 f28d96d3 2021-01-25 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
  2 3e4749f7 2020-10-02 op .\"
  3 3e4749f7 2020-10-02 op .\" Permission to use, copy, modify, and distribute this software for any
  4 3e4749f7 2020-10-02 op .\" purpose with or without fee is hereby granted, provided that the above
  5 3e4749f7 2020-10-02 op .\" copyright notice and this permission notice appear in all copies.
  6 3e4749f7 2020-10-02 op .\"
  7 3e4749f7 2020-10-02 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 3e4749f7 2020-10-02 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 3e4749f7 2020-10-02 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 3e4749f7 2020-10-02 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 3e4749f7 2020-10-02 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 3e4749f7 2020-10-02 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 3e4749f7 2020-10-02 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 39a7b611 2021-01-30 op .Dd $Mdocdate: January 30 2021$
 15 3f47867e 2021-04-16 op .Dt GMID 1
 16 3e4749f7 2020-10-02 op .Os
 17 3e4749f7 2020-10-02 op .Sh NAME
 18 3e4749f7 2020-10-02 op .Nm gmid
 19 714685c1 2021-01-30 op .Nd simple and secure Gemini server
 20 3e4749f7 2020-10-02 op .Sh SYNOPSIS
 21 3e4749f7 2020-10-02 op .Nm
 22 3e4749f7 2020-10-02 op .Bk -words
 23 38d4db74 2021-02-04 op .Op Fl fnv
 24 15902770 2021-01-15 op .Op Fl c Ar config
 25 8b743dda 2021-06-29 op .Op Fl D Ar macro Ns = Ns Ar value
 26 8e8b2e25 2021-04-28 op .Op Fl P Ar pidfile
 27 38d4db74 2021-02-04 op .Ek
 28 38d4db74 2021-02-04 op .Nm
 29 38d4db74 2021-02-04 op .Bk -words
 30 ba65dcc8 2021-06-29 op .Op Fl 6hVv
 31 f28d96d3 2021-01-25 op .Op Fl d Pa certs-dir
 32 f28d96d3 2021-01-25 op .Op Fl H Ar hostname
 33 721e2325 2020-11-18 op .Op Fl p Ar port
 34 f28d96d3 2021-01-25 op .Op Fl x Pa cgi
 35 f28d96d3 2021-01-25 op .Op Pa dir
 36 3e4749f7 2020-10-02 op .Ek
 37 3e4749f7 2020-10-02 op .Sh DESCRIPTION
 38 3e4749f7 2020-10-02 op .Nm
 39 8ff40039 2021-05-24 op is a simple and minimal gemini server that can serve static files,
 40 8ff40039 2021-05-24 op execute CGI scripts and talk to FastCGI applications.
 41 eb699783 2021-01-18 op It can run without a configuration file with a limited set of features
 42 eb699783 2021-01-18 op available.
 43 3007f565 2021-02-04 op .Pp
 44 3007f565 2021-02-04 op .Nm
 45 3007f565 2021-02-04 op rereads the configuration file when it receives
 46 3007f565 2021-02-04 op .Dv SIGHUP .
 47 3e4749f7 2020-10-02 op .Pp
 48 eb699783 2021-01-18 op The options are as follows:
 49 f28d96d3 2021-01-25 op .Bl -tag -width 14m
 50 eb699783 2021-01-18 op .It Fl c Pa config
 51 f28d96d3 2021-01-25 op Specify the configuration file.
 52 8b743dda 2021-06-29 op .It Fl D Ar macro Ns = Ns Ar value
 53 8b743dda 2021-06-29 op Define
 54 8b743dda 2021-06-29 op .Ar macro
 55 8b743dda 2021-06-29 op to be set to
 56 8b743dda 2021-06-29 op .Ar value
 57 8b743dda 2021-06-29 op on the command line.
 58 8b743dda 2021-06-29 op Overrides the definition of
 59 8b743dda 2021-06-29 op .Ar macro
 60 8b743dda 2021-06-29 op in the config file if present.
 61 46af8c6c 2021-01-27 op .It Fl f
 62 46af8c6c 2021-01-27 op Stays and logs on the foreground.
 63 eb699783 2021-01-18 op .It Fl n
 64 eb699783 2021-01-18 op Check that the configuration is valid, but don't start the server.
 65 8e8b2e25 2021-04-28 op .It Fl P Pa pidfile
 66 2b520ad5 2021-07-09 op Write the daemon pid to the given location.
 67 2b520ad5 2021-07-09 op .Ar pidfile
 68 2b520ad5 2021-07-09 op will also act as lock: if another process is holding a lock on that
 69 2b520ad5 2021-07-09 op file,
 70 8e8b2e25 2021-04-28 op .Nm
 71 2b520ad5 2021-07-09 op will refuse to start.
 72 eb699783 2021-01-18 op .El
 73 3e4749f7 2020-10-02 op .Pp
 74 eb699783 2021-01-18 op If no configuration file is given,
 75 fab952e1 2020-10-03 op .Nm
 76 f28d96d3 2021-01-25 op will look for the following options
 77 f28d96d3 2021-01-25 op .Bl -tag -width 14m
 78 85dff1f9 2021-01-11 op .It Fl 6
 79 85dff1f9 2021-01-11 op Enable IPv6.
 80 f28d96d3 2021-01-25 op .It Fl d Pa certs-path
 81 f28d96d3 2021-01-25 op Directory where certificates for the config-less mode are stored.
 82 f28d96d3 2021-01-25 op By default is
 83 f28d96d3 2021-01-25 op .Pa $XDG_DATA_HOME/gmid ,
 84 f28d96d3 2021-01-25 op i.e.
 85 f28d96d3 2021-01-25 op .Pa ~/.local/share/gmid .
 86 71cf3975 2021-01-25 op .It Fl H Ar hostname
 87 2b520ad5 2021-07-09 op The hostname
 88 2b520ad5 2021-07-09 op .Ar localhost
 89 2b520ad5 2021-07-09 op by default.
 90 f28d96d3 2021-01-25 op Certificates for the given
 91 f28d96d3 2021-01-25 op .Ar hostname
 92 f28d96d3 2021-01-25 op are searched inside the
 93 f28d96d3 2021-01-25 op .Pa certs-dir
 94 f28d96d3 2021-01-25 op directory given with the
 95 f28d96d3 2021-01-25 op .Fl d
 96 f28d96d3 2021-01-25 op option.
 97 714685c1 2021-01-30 op They have the form
 98 f28d96d3 2021-01-25 op .Pa hostname.cert.pem
 99 f28d96d3 2021-01-25 op and
100 f28d96d3 2021-01-25 op .Pa hostname.key.pem .
101 1de92289 2021-04-15 op If a certificate or key don't exists for a given hostname they
102 714685c1 2021-01-30 op will be automatically generated.
103 ba65dcc8 2021-06-29 op .It Fl h , Fl -help
104 fab952e1 2020-10-03 op Print the usage and exit.
105 721e2325 2020-11-18 op .It Fl p Ar port
106 eb699783 2021-01-18 op The port to listen on, by default 1965.
107 ba65dcc8 2021-06-29 op .It Fl V , Fl -version
108 ba65dcc8 2021-06-29 op Print the version and exit.
109 8904fa0e 2021-01-27 op .It Fl v
110 3abf91b0 2021-02-07 op Verbose mode.
111 3abf91b0 2021-02-07 op Multiple
112 3abf91b0 2021-02-07 op .Fl v
113 3abf91b0 2021-02-07 op options increase the verbosity.
114 f28d96d3 2021-01-25 op .It Fl x Pa path
115 eb699783 2021-01-18 op Enable execution of CGI scripts.
116 eb699783 2021-01-18 op See the description of the
117 eb699783 2021-01-18 op .Ic cgi
118 eb699783 2021-01-18 op option in the section
119 eb699783 2021-01-18 op .Sq Servers
120 eb699783 2021-01-18 op below to learn how
121 f28d96d3 2021-01-25 op .Pa path
122 eb699783 2021-01-18 op is processed.
123 eb699783 2021-01-18 op Cannot be provided more than once.
124 f28d96d3 2021-01-25 op .It Pa dir
125 f28d96d3 2021-01-25 op The root directory to serve.
126 f28d96d3 2021-01-25 op By default the current working directory is assumed.
127 3e4749f7 2020-10-02 op .El
128 eb699783 2021-01-18 op .Sh CONFIGURATION FILE
129 8b743dda 2021-06-29 op The configuration file is divided into three sections:
130 eb699783 2021-01-18 op .Bl -tag -width xxxx
131 8b743dda 2021-06-29 op .It Sy Macros
132 8b743dda 2021-06-29 op User-defined variables may be defined and used later, simplifying the
133 8b743dda 2021-06-29 op configuration file.
134 eb699783 2021-01-18 op .It Sy Global Options
135 eb699783 2021-01-18 op Global settings for
136 eb699783 2021-01-18 op .Nm .
137 eb699783 2021-01-18 op .It Sy Servers
138 f28d96d3 2021-01-25 op Virtual hosts definition.
139 eb699783 2021-01-18 op .El
140 eb699783 2021-01-18 op .Pp
141 eb699783 2021-01-18 op Within the sections, empty lines are ignored and comments can be put
142 eb699783 2021-01-18 op anywhere in the file using a hash mark
143 eb699783 2021-01-18 op .Pq Sq # ,
144 eb699783 2021-01-18 op and extend to the end of the current line.
145 eb699783 2021-01-18 op A boolean is either the symbol
146 eb699783 2021-01-18 op .Sq on
147 eb699783 2021-01-18 op or
148 eb699783 2021-01-18 op .Sq off .
149 f28d96d3 2021-01-25 op A string is a sequence of characters wrapped in double quotes,
150 f28d96d3 2021-01-25 op .Dq like this .
151 eaf7f776 2021-06-29 op Multiple strings one next to the other are joined into a single
152 eaf7f776 2021-06-29 op string:
153 eaf7f776 2021-06-29 op .Bd -literal -offset indent
154 eaf7f776 2021-06-29 op # equivalent to "temporary-failure"
155 eaf7f776 2021-06-29 op block return 40 "temporary" "-" "failure"
156 eaf7f776 2021-06-29 op .Ed
157 8b743dda 2021-06-29 op .Pp
158 2b520ad5 2021-07-09 op Furthermore, quoting is necessary only when a string needs to contain
159 528f37cd 2021-07-09 op special characters
160 528f37cd 2021-07-09 op .Pq like spaces or punctuation ,
161 528f37cd 2021-07-09 op something that looks like a number or a reserved keyword.
162 2b520ad5 2021-07-09 op The last example could have been written also as:
163 2b520ad5 2021-07-09 op .Bd -literal -offset indent
164 2b520ad5 2021-07-09 op block return 40 temporary "-" failure
165 2b520ad5 2021-07-09 op .Ed
166 2b520ad5 2021-07-09 op .Pp
167 8b743dda 2021-06-29 op Strict ordering of the sections is not enforced, so that is possible
168 8b743dda 2021-06-29 op to mix macros, options and
169 8b743dda 2021-06-29 op .Ic server
170 8b743dda 2021-06-29 op blocks.
171 8b743dda 2021-06-29 op However, defining all the
172 8b743dda 2021-06-29 op .Ic server
173 8b743dda 2021-06-29 op blocks after the macros and the global options is recommended.
174 528f37cd 2021-07-09 op .Pp
175 528f37cd 2021-07-09 op Newlines are often optional, except around top-level instructions, and
176 528f37cd 2021-07-09 op semicolons
177 528f37cd 2021-07-09 op .Dq \&;
178 528f37cd 2021-07-09 op can also be optionally used to separate options.
179 528f37cd 2021-07-09 op .Pp
180 528f37cd 2021-07-09 op Additional configuration files can be included with the
181 528f37cd 2021-07-09 op .Ic include
182 528f37cd 2021-07-09 op keyword, for example:
183 528f37cd 2021-07-09 op .Bd -literal -offset indent
184 528f37cd 2021-07-09 op include "/etc/gmid.conf.local"
185 528f37cd 2021-07-09 op .Ed
186 8b743dda 2021-06-29 op .Ss Macros
187 8b743dda 2021-06-29 op Macros can be defined that will later be expanded in context.
188 8b743dda 2021-06-29 op Macro names must start with a letter, digit or underscore and may
189 8b743dda 2021-06-29 op contain any of those characters.
190 4f9a2760 2021-07-02 op Macros names may not be reserved words.
191 bfb076ed 2021-06-29 op Macros are not expanded inside quotes.
192 528f37cd 2021-07-09 op .Pp
193 528f37cd 2021-07-09 op Two kinds of macros are supported: variable-like and proper macros.
194 528f37cd 2021-07-09 op When a macro is invoked with a
195 528f37cd 2021-07-09 op .Dq $
196 528f37cd 2021-07-09 op before its name its expanded as a string, whereas when it's invoked
197 528f37cd 2021-07-09 op with a
198 528f37cd 2021-07-09 op .Dq @
199 528f37cd 2021-07-09 op its expanded in-place.
200 8b743dda 2021-06-29 op .Pp
201 8b743dda 2021-06-29 op For example:
202 8b743dda 2021-06-29 op .Bd -literal -offset indent
203 8b743dda 2021-06-29 op dir = "/var/gemini"
204 8b743dda 2021-06-29 op cert = "/etc/keys"
205 528f37cd 2021-07-09 op common = "lang it; auto index on"
206 8b743dda 2021-06-29 op 
207 8b743dda 2021-06-29 op server "foo" {
208 4ede0fe4 2021-06-29 op 	root $dir "/foo"      # -> /var/gemini/foo
209 4ede0fe4 2021-06-29 op 	cert $cert "/foo.crt" # -> /etc/keys/foo.crt
210 4ede0fe4 2021-06-29 op 	key  $cert "/foo.pem" # -> /etc/keys/foo.pem
211 528f37cd 2021-07-09 op 	@common
212 8b743dda 2021-06-29 op }
213 8b743dda 2021-06-29 op .Ed
214 eb699783 2021-01-18 op .Ss Global Options
215 eb699783 2021-01-18 op .Bl -tag -width 12m
216 ae08ec7d 2021-01-25 op .It Ic chroot Pa path
217 ae08ec7d 2021-01-25 op .Xr chroot 2
218 ae08ec7d 2021-01-25 op the process to the given
219 ae08ec7d 2021-01-25 op .Pa path .
220 ae08ec7d 2021-01-25 op The daemon has to be run with root privileges and thus the option
221 ae08ec7d 2021-01-25 op .Ic user
222 714685c1 2021-01-30 op needs to be provided, so privileges can be dropped.
223 714685c1 2021-01-30 op Note that
224 ae08ec7d 2021-01-25 op .Nm
225 714685c1 2021-01-30 op will enter the chroot after loading the TLS keys, but before opening
226 714685c1 2021-01-30 op the virtual host root directories.
227 714685c1 2021-01-30 op It's recommended to keep the TLS keys outside the chroot.
228 ae08ec7d 2021-01-25 op Future version of
229 ae08ec7d 2021-01-25 op .Nm
230 1de92289 2021-04-15 op may enforce this.
231 2b92a447 2021-02-06 op .It Ic ipv6 Ar bool
232 2b520ad5 2021-07-09 op Enable or disable IPv6 support, off by default.
233 d19951cf 2021-07-09 op .It Ic map Ar mime-type Cm to-ext Ar file-extension
234 2b520ad5 2021-07-09 op Map
235 2b520ad5 2021-07-09 op .Ar mime-type
236 2b92a447 2021-02-06 op to the given
237 2b520ad5 2021-07-09 op .Ar file-extension .
238 2b92a447 2021-02-06 op Both argument are strings.
239 2b92a447 2021-02-06 op .It Ic port Ar portno
240 2b92a447 2021-02-06 op The port to listen on.
241 2b520ad5 2021-07-09 op 1965 by default.
242 a709ddf5 2021-02-07 op .It Ic prefork Ar number
243 a709ddf5 2021-02-07 op Run the specified number of server processes.
244 a709ddf5 2021-02-07 op This increases the performance and prevents delays when connecting to
245 a709ddf5 2021-02-07 op a server.
246 2b520ad5 2021-07-09 op When not in config-less mode,
247 a709ddf5 2021-02-07 op .Nm
248 2b520ad5 2021-07-09 op runs 3 server processes by default.
249 2c3e53da 2021-03-03 op The maximum number allowed is 16.
250 2b92a447 2021-02-06 op .It Ic protocols Ar string
251 2b92a447 2021-02-06 op Specify the TLS protocols to enable.
252 2b92a447 2021-02-06 op Refer to
253 2b92a447 2021-02-06 op .Xr tls_config_parse_protocols 3
254 2b92a447 2021-02-06 op for the valid protocol string values.
255 2b92a447 2021-02-06 op By default, both TLSv1.3 and TLSv1.2 are enabled.
256 2b92a447 2021-02-06 op Use
257 2b92a447 2021-02-06 op .Dq tlsv1.3
258 2b92a447 2021-02-06 op to enable only TLSv1.3.
259 ae08ec7d 2021-01-25 op .It Ic user Ar string
260 ae08ec7d 2021-01-25 op Run the daemon as the given user.
261 eb699783 2021-01-18 op .El
262 eb699783 2021-01-18 op .Ss Servers
263 eb699783 2021-01-18 op Every virtual host is defined by a
264 eb699783 2021-01-18 op .Ic server
265 eb699783 2021-01-18 op block:
266 eb699783 2021-01-18 op .Bl -tag -width Ds
267 eb699783 2021-01-18 op .It Ic server Ar hostname Brq ...
268 75fbb178 2021-01-28 op Match the server name using shell globbing rules.
269 2b520ad5 2021-07-09 op It can be an explicit name,
270 de27389e 2021-01-21 op .Ar www.example.com ,
271 de27389e 2021-01-21 op or a name including a wildcards,
272 de27389e 2021-01-21 op .Ar *.example.com .
273 eb699783 2021-01-18 op .El
274 eb699783 2021-01-18 op .Pp
275 eb699783 2021-01-18 op Followed by a block of options that is enclosed in curly brackets:
276 eb699783 2021-01-18 op .Bl -tag -width Ds
277 cc8c2901 2021-04-29 op .It Ic alias Ar name
278 cc8c2901 2021-04-29 op Specify an additional alias
279 cc8c2901 2021-04-29 op .Ar name
280 cc8c2901 2021-04-29 op for this server.
281 2b92a447 2021-02-06 op .It Ic auto Ic index Ar bool
282 2b92a447 2021-02-06 op If no index file is found, automatically generate a directory listing.
283 2b520ad5 2021-07-09 op Disabled by default.
284 2b92a447 2021-02-06 op .It Ic block Op Ic return Ar code Op Ar meta
285 2b92a447 2021-02-06 op Send a reply and close the connection;
286 2b520ad5 2021-07-09 op by default
287 2b92a447 2021-02-06 op .Ar code
288 2b92a447 2021-02-06 op is 40
289 2b92a447 2021-02-06 op and
290 2b92a447 2021-02-06 op .Ar meta
291 2b92a447 2021-02-06 op is
292 2b520ad5 2021-07-09 op .Dq temporary failure .
293 2b92a447 2021-02-06 op If
294 2b92a447 2021-02-06 op .Ar code
295 2b92a447 2021-02-06 op is in the 3x range, then
296 2b92a447 2021-02-06 op .Ar meta
297 2b520ad5 2021-07-09 op is mandatory.
298 2b92a447 2021-02-06 op Inside
299 2b92a447 2021-02-06 op .Ar meta ,
300 2b520ad5 2021-07-09 op the following special sequences are supported:
301 fd1ae83d 2021-06-11 op .Bl -tag -width Ds -compact
302 2b92a447 2021-02-06 op .It \&%\&%
303 2b92a447 2021-02-06 op is replaced with a single
304 2b92a447 2021-02-06 op .Sq \&% .
305 2b92a447 2021-02-06 op .It \&%p
306 2b92a447 2021-02-06 op is replaced with the request path.
307 2b92a447 2021-02-06 op .It \&%q
308 2b92a447 2021-02-06 op is replaced with the query string of the request.
309 2b92a447 2021-02-06 op .It \&%P
310 2b92a447 2021-02-06 op is replaced with the server port.
311 2b92a447 2021-02-06 op .It \&%N
312 2b92a447 2021-02-06 op is replaced with the server name.
313 2b92a447 2021-02-06 op .El
314 eb699783 2021-01-18 op .It Ic cert Pa file
315 eb699783 2021-01-18 op Path to the certificate to use for this server.
316 eb699783 2021-01-18 op The
317 eb699783 2021-01-18 op .Pa file
318 eb699783 2021-01-18 op should contain a PEM encoded certificate.
319 eb699783 2021-01-18 op This option is mandatory.
320 eb699783 2021-01-18 op .It Ic cgi Pa path
321 87f2b68b 2021-02-02 op Execute CGI scripts that matches
322 eb699783 2021-01-18 op .Pa path
323 87f2b68b 2021-02-02 op using shell globbing rules.
324 6119e13e 2021-01-19 op .It Ic default type Ar string
325 6119e13e 2021-01-19 op Set the default media type that is used if the media type for a
326 6119e13e 2021-01-19 op specified extension is not found.
327 6119e13e 2021-01-19 op If not specified, the
328 6119e13e 2021-01-19 op .Ic default type
329 6119e13e 2021-01-19 op is set to
330 6119e13e 2021-01-19 op .Dq application/octet-stream .
331 2b92a447 2021-02-06 op .It Ic entrypoint Pa path
332 dafaf467 2021-04-15 op Handle all the requests for the current virtual host using the
333 dafaf467 2021-04-15 op CGI script at
334 2b520ad5 2021-07-09 op .Pa path ,
335 2b520ad5 2021-07-09 op relative to the current document root.
336 efacb859 2021-07-09 op .It Ic env Ar name Cm = Ar value
337 9cc630aa 2021-04-28 op Set the environment variable
338 9cc630aa 2021-04-28 op .Ar name
339 9cc630aa 2021-04-28 op to
340 9cc630aa 2021-04-28 op .Ar value
341 9cc630aa 2021-04-28 op when executing CGI scripts.
342 9cc630aa 2021-04-28 op Can be provided more than once.
343 8ff40039 2021-05-24 op .\" don't document the "spawn <prog>" form because it probably won't
344 ada16f87 2021-06-11 op .\" be kept.
345 762b9b99 2021-07-09 op .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
346 8ff40039 2021-05-24 op Enable FastCGI instead of serving files.
347 8ff40039 2021-05-24 op The
348 8ff40039 2021-05-24 op .Pa socket
349 2b520ad5 2021-07-09 op can either be a UNIX-domain socket or a TCP socket.
350 8ff40039 2021-05-24 op If the FastCGI application is listening on a UNIX domain socket,
351 8ff40039 2021-05-24 op .Pa socket
352 8ff40039 2021-05-24 op is a local path name within the
353 8ff40039 2021-05-24 op .Xr chroot 2
354 8ff40039 2021-05-24 op root directory of
355 8ff40039 2021-05-24 op .Nm .
356 8ff40039 2021-05-24 op Otherwise, the
357 8ff40039 2021-05-24 op .Ic tcp
358 8ff40039 2021-05-24 op keyword must be provided and
359 8ff40039 2021-05-24 op .Pa socket
360 8ff40039 2021-05-24 op is interpreted as a hostname or an IP address.
361 8ff40039 2021-05-24 op .Ar port
362 8ff40039 2021-05-24 op can be either a port number or the name of a service enclosed in
363 8ff40039 2021-05-24 op double quotes.
364 2b520ad5 2021-07-09 op If not specified defaults to 9000.
365 2b92a447 2021-02-06 op .It Ic index Ar string
366 2b92a447 2021-02-06 op Set the directory index file.
367 2b92a447 2021-02-06 op If not specified, it defaults to
368 2b92a447 2021-02-06 op .Pa index.gmi .
369 2b92a447 2021-02-06 op .It Ic key Pa file
370 2b92a447 2021-02-06 op Specify the private key to use for this server.
371 2b92a447 2021-02-06 op The
372 2b92a447 2021-02-06 op .Pa file
373 2b92a447 2021-02-06 op should contain a PEM encoded private key.
374 2b92a447 2021-02-06 op This option is mandatory.
375 05c23a54 2021-01-19 op .It Ic lang Ar string
376 05c23a54 2021-01-19 op Specify the language tag for the text/gemini content served.
377 05c23a54 2021-01-19 op If not specified, no
378 05c23a54 2021-01-19 op .Dq lang
379 05c23a54 2021-01-19 op parameter will be added in the response.
380 c8b74339 2021-01-24 op .It Ic location Pa path Brq ...
381 c8b74339 2021-01-24 op Specify server configuration rules for a specific location.
382 c8b74339 2021-01-24 op The
383 c8b74339 2021-01-24 op .Pa path
384 c8b74339 2021-01-24 op argument will be matched against the request path with shell globbing
385 c8b74339 2021-01-24 op rules.
386 6016a593 2021-01-30 op In case of multiple location statements in the same context, the first
387 6016a593 2021-01-30 op matching location will be put into effect and the later ones ignored.
388 6016a593 2021-01-30 op Therefore is advisable to match for more specific paths first and for
389 6016a593 2021-01-30 op generic ones later on.
390 c8b74339 2021-01-24 op A
391 c8b74339 2021-01-24 op .Ic location
392 c8b74339 2021-01-24 op section may include most of the server configuration rules
393 c8b74339 2021-01-24 op except
394 3d132b28 2021-07-09 op .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
395 3d132b28 2021-07-09 op .Ic location No and Ic param .
396 2c43dcce 2021-06-17 op .It Ic log Ar bool
397 2c43dcce 2021-06-17 op Enable or disable the logging for the current server or location block.
398 efacb859 2021-07-09 op .It Ic param Ar name Cm = Ar value
399 ada16f87 2021-06-11 op Set the param
400 ada16f87 2021-06-11 op .Ar name
401 ada16f87 2021-06-11 op to
402 ada16f87 2021-06-11 op .Ar value
403 ada16f87 2021-06-11 op for FastCGI.
404 2b92a447 2021-02-06 op .It Ic root Pa directory
405 2b520ad5 2021-07-09 op Specify the root directory for this server
406 2b520ad5 2021-07-09 op .Pq alas the current Dq document root .
407 2b520ad5 2021-07-09 op It's relative to the chroot if enabled.
408 02be96c6 2021-02-09 op .It Ic require Ic client Ic ca Pa path
409 02be96c6 2021-02-09 op Allow requests only from clients that provide a certificate signed by
410 02be96c6 2021-02-09 op the CA certificate in
411 02be96c6 2021-02-09 op .Pa path .
412 02be96c6 2021-02-09 op It needs to be a PEM-encoded certificate and it's not relative to the
413 02be96c6 2021-02-09 op chroot.
414 6abda252 2021-02-06 op .It Ic strip Ar number
415 6abda252 2021-02-06 op Strip
416 6abda252 2021-02-06 op .Ar number
417 0773413c 2021-05-15 op components from the beginning of the path before doing a lookup in the
418 0773413c 2021-05-15 op root directory.
419 0773413c 2021-05-15 op It's also considered for the
420 6abda252 2021-02-06 op .Ar meta
421 2b92a447 2021-02-06 op parameter in the scope of a
422 6abda252 2021-02-06 op .Ic block return .
423 6abda252 2021-02-06 op .El
424 72342dc9 2020-11-06 op .Sh CGI
425 87f2b68b 2021-02-02 op When a request for an executable file matches the
426 87f2b68b 2021-02-02 op .Ic cgi
427 87f2b68b 2021-02-02 op rule, that file will be execute and its output fed to the client.
428 72342dc9 2020-11-06 op .Pp
429 ee655e64 2021-02-01 op The CGI scripts are executed in the directory they reside and inherit
430 a7b9bb4d 2021-01-24 op the environment from
431 0ed56567 2020-11-06 op .Nm
432 0ed56567 2020-11-06 op with these additional variables set:
433 ee655e64 2021-02-01 op .Bl -tag -width 24m
434 28ec6178 2021-01-24 op .It Ev GATEWAY_INTERFACE
435 ee655e64 2021-02-01 op .Dq CGI/1.1
436 ee655e64 2021-02-01 op .It Ev GEMINI_DOCUMENT_ROOT
437 ee655e64 2021-02-01 op The root directory of the virtual host.
438 ee655e64 2021-02-01 op .It Ev GEMINI_SCRIPT_FILENAME
439 ee655e64 2021-02-01 op Full path to the CGI script being executed.
440 ee655e64 2021-02-01 op .It Ev GEMINI_URL
441 ee655e64 2021-02-01 op The full IRI of the request.
442 ee655e64 2021-02-01 op .It Ev GEMINI_URL_PATH
443 ee655e64 2021-02-01 op The path of the request.
444 ee655e64 2021-02-01 op .It Ev PATH_INFO
445 ee655e64 2021-02-01 op The portion of the requested path that is derived from the the IRI
446 ee655e64 2021-02-01 op path hierarchy following the part that identifies the script itself.
447 ee655e64 2021-02-01 op Can be unset.
448 ee655e64 2021-02-01 op .It Ev PATH_TRANSLATED
449 ee655e64 2021-02-01 op Present if and only if
450 ee655e64 2021-02-01 op .Ev PATH_INFO
451 ee655e64 2021-02-01 op is set.
452 ee655e64 2021-02-01 op It represent the translation of the
453 ee655e64 2021-02-01 op .Ev PATH_INFO .
454 ee655e64 2021-02-01 op .Nm
455 ee655e64 2021-02-01 op builds this by appending the
456 ee655e64 2021-02-01 op .Ev PATH_INFO
457 ee655e64 2021-02-01 op to the virtual host directory root.
458 ee655e64 2021-02-01 op .It Ev QUERY_STRING
459 ee655e64 2021-02-01 op The decoded query string.
460 ee655e64 2021-02-01 op .It Ev REMOTE_ADDR , Ev REMOTE_HOST
461 ee655e64 2021-02-01 op Textual representation of the client IP.
462 ee655e64 2021-02-01 op .It Ev REQUEST_METHOD
463 ee655e64 2021-02-01 op This is present only for RFC3875 (CGI) compliance.
464 ee655e64 2021-02-01 op It's always set to the empty string.
465 ee655e64 2021-02-01 op .It Ev SCRIPT_NAME
466 ee655e64 2021-02-01 op The part of the
467 ee655e64 2021-02-01 op .Ev GEMINI_URL_PATH
468 ee655e64 2021-02-01 op that identifies the current CGI script.
469 ee655e64 2021-02-01 op .It Ev SERVER_NAME
470 ee655e64 2021-02-01 op The name of the server
471 ee655e64 2021-02-01 op .It Ev SERVER_PORT
472 ee655e64 2021-02-01 op The port the server is listening on.
473 28ec6178 2021-01-24 op .It Ev SERVER_PROTOCOL
474 ee655e64 2021-02-01 op .Dq GEMINI
475 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
476 ee655e64 2021-02-01 op The name and version of the server, i.e.
477 b79b2d81 2021-07-10 op .Dq gmid/1.7
478 677afbd3 2020-12-02 op .It Ev AUTH_TYPE
479 28ec6178 2021-01-24 op The string "Certificate" if the client used a certificate, otherwise
480 28ec6178 2021-01-24 op unset.
481 677afbd3 2020-12-02 op .It Ev REMOTE_USER
482 677afbd3 2020-12-02 op The subject of the client certificate if provided, otherwise unset.
483 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_ISSUER
484 28ec6178 2021-01-24 op The is the issuer of the client certificate if provided, otherwise
485 28ec6178 2021-01-24 op unset.
486 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_HASH
487 677afbd3 2020-12-02 op The hash of the client certificate if provided, otherwise unset.
488 ee655e64 2021-02-01 op The format is
489 ee655e64 2021-02-01 op .Dq ALGO:HASH .
490 89541eee 2021-04-13 op .It Ev TLS_VERSION
491 89541eee 2021-04-13 op The TLS version negotiated with the peer.
492 89541eee 2021-04-13 op .It Ev TLS_CIPHER
493 89541eee 2021-04-13 op The cipher suite negotiated with the peer.
494 89541eee 2021-04-13 op .It Ev TLS_CIPHER_STRENGTH
495 89541eee 2021-04-13 op The strength in bits for the symmetric cipher that is being used with
496 89541eee 2021-04-13 op the peer.
497 b63e30ff 2021-02-07 op .It Ev TLS_CLIENT_NOT_AFTER
498 b63e30ff 2021-02-07 op The time corresponding to the end of the validity period of the peer
499 b63e30ff 2021-02-07 op certificate in the ISO 8601 format
500 b63e30ff 2021-02-07 op .Pq e.g. Dq 2021-02-07T20:17:41Z .
501 b63e30ff 2021-02-07 op .It Ev TLS_CLIENT_NOT_BEFORE
502 b63e30ff 2021-02-07 op The time corresponding to the start of the validity period of the peer
503 b63e30ff 2021-02-07 op certificate in the ISO 8601 format.
504 0ed56567 2020-11-06 op .El
505 ada16f87 2021-06-11 op .Sh FastCGI
506 ada16f87 2021-06-11 op .Nm
507 ada16f87 2021-06-11 op optionally supports FastCGI.
508 ada16f87 2021-06-11 op A
509 ada16f87 2021-06-11 op .Ic fastcgi
510 ada16f87 2021-06-11 op rule must be present in a server or location block.
511 ada16f87 2021-06-11 op Then, all requests matching that server or location will be handled
512 ada16f87 2021-06-11 op via the specified FastCGI backend.
513 a5d310bc 2020-11-10 op .Pp
514 ada16f87 2021-06-11 op By default the following variables
515 ada16f87 2021-06-11 op .Pq parameters
516 ada16f87 2021-06-11 op are sent, and carry the same semantics as with CGI.
517 ada16f87 2021-06-11 op More parameters can be added with the
518 ada16f87 2021-06-11 op .Ic param
519 ada16f87 2021-06-11 op option.
520 2b520ad5 2021-07-09 op .Pp
521 ada16f87 2021-06-11 op .Bl -bullet -compact
522 ada16f87 2021-06-11 op .It
523 ada16f87 2021-06-11 op GATEWAY_INTERFACE
524 ada16f87 2021-06-11 op .It
525 ada16f87 2021-06-11 op GEMINI_URL_PATH
526 ada16f87 2021-06-11 op .It
527 ada16f87 2021-06-11 op QUERY_STRING
528 ada16f87 2021-06-11 op .It
529 ada16f87 2021-06-11 op REMOTE_ADDR
530 ada16f87 2021-06-11 op .It
531 ada16f87 2021-06-11 op REMOTE_HOST
532 ada16f87 2021-06-11 op .It
533 ada16f87 2021-06-11 op REQUEST_METHOD
534 ada16f87 2021-06-11 op .It
535 ada16f87 2021-06-11 op SERVER_NAME
536 ada16f87 2021-06-11 op .It
537 ada16f87 2021-06-11 op SERVER_PROTOCOL
538 ada16f87 2021-06-11 op .It
539 ada16f87 2021-06-11 op SERVER_SOFTWARE
540 ada16f87 2021-06-11 op .It
541 ada16f87 2021-06-11 op AUTH_TYPE
542 ada16f87 2021-06-11 op .It
543 ada16f87 2021-06-11 op REMOTE_USER
544 ada16f87 2021-06-11 op .It
545 ada16f87 2021-06-11 op TLS_CLIENT_ISSUER
546 ada16f87 2021-06-11 op .It
547 ada16f87 2021-06-11 op TLS_CLIENT_HASH
548 ada16f87 2021-06-11 op .It
549 ada16f87 2021-06-11 op TLS_VERSION
550 ada16f87 2021-06-11 op .It
551 ada16f87 2021-06-11 op TLS_CIPHER
552 ada16f87 2021-06-11 op .It
553 ada16f87 2021-06-11 op TLS_CIPHER_STRENGTH
554 ada16f87 2021-06-11 op .It
555 ada16f87 2021-06-11 op TLS_CLIENT_NOT_BEFORE
556 ada16f87 2021-06-11 op .It
557 ada16f87 2021-06-11 op TLS_CLIENT_NOT_AFTER
558 ada16f87 2021-06-11 op .El
559 75fbb178 2021-01-28 op .Sh MIME
560 75fbb178 2021-01-28 op To auto-detect the MIME type of the response
561 75fbb178 2021-01-28 op .Nm
562 75fbb178 2021-01-28 op looks at the file extension and consults its internal table.
563 75fbb178 2021-01-28 op By default the following mappings are loaded, but they can be
564 75fbb178 2021-01-28 op overridden or extended using the
565 d19951cf 2021-07-09 op .Ic map
566 75fbb178 2021-01-28 op configuration option.
567 75fbb178 2021-01-28 op If no MIME is found, the value of
568 75fbb178 2021-01-28 op .Ic default type
569 75fbb178 2021-01-28 op matching the file
570 75fbb178 2021-01-28 op .Ic location
571 75fbb178 2021-01-28 op will be used, which is
572 75fbb178 2021-01-28 op .Dq application/octet-stream
573 75fbb178 2021-01-28 op by default.
574 75fbb178 2021-01-28 op .Pp
575 75fbb178 2021-01-28 op .Bl -tag -offset indent -width 14m -compact
576 4d820b6c 2021-04-21 op .It diff
577 4d820b6c 2021-04-21 op text/x-patch
578 75fbb178 2021-01-28 op .It gemini, gmi
579 75fbb178 2021-01-28 op text/gemini
580 75fbb178 2021-01-28 op .It gif
581 75fbb178 2021-01-28 op image/gif
582 75fbb178 2021-01-28 op .It jpeg
583 75fbb178 2021-01-28 op image/jpeg
584 75fbb178 2021-01-28 op .It jpg
585 75fbb178 2021-01-28 op image/jpeg
586 75fbb178 2021-01-28 op .It markdown, md
587 75fbb178 2021-01-28 op text/markdown
588 4d820b6c 2021-04-21 op .It patch
589 4d820b6c 2021-04-21 op text/x-patch
590 75fbb178 2021-01-28 op .It pdf
591 75fbb178 2021-01-28 op application/pdf
592 75fbb178 2021-01-28 op .It png
593 75fbb178 2021-01-28 op image/png
594 75fbb178 2021-01-28 op .It svg
595 75fbb178 2021-01-28 op image/svg+xml
596 75fbb178 2021-01-28 op .It txt
597 75fbb178 2021-01-28 op text/plain
598 75fbb178 2021-01-28 op .It xml
599 75fbb178 2021-01-28 op text/xml
600 75fbb178 2021-01-28 op .El
601 3e4749f7 2020-10-02 op .Sh EXAMPLES
602 f28d96d3 2021-01-25 op Serve the current directory
603 6980aad6 2020-10-02 op .Bd -literal -offset indent
604 f28d96d3 2021-01-25 op $ gmid .
605 6980aad6 2020-10-02 op .Ed
606 3e4749f7 2020-10-02 op .Pp
607 f28d96d3 2021-01-25 op To serve the directory
608 f28d96d3 2021-01-25 op .Pa docs
609 f28d96d3 2021-01-25 op and enable CGI scripts inside
610 2b520ad5 2021-07-09 op .Pa docs/cgi
611 0ed56567 2020-11-06 op .Bd -literal -offset indent
612 f28d96d3 2021-01-25 op $ mkdir docs/cgi
613 b7a99061 2021-04-15 op $ cat <<EOF > docs/cgi/hello
614 0ed56567 2020-11-06 op #!/bin/sh
615 0ed56567 2020-11-06 op printf "20 text/plain\\r\\n"
616 f28d96d3 2021-01-25 op echo "hello world"
617 0ed56567 2020-11-06 op EOF
618 f28d96d3 2021-01-25 op $ chmod +x docs/cgi/hello
619 b890467e 2021-03-20 op $ gmid -x '/cgi/*' docs
620 0ed56567 2020-11-06 op .Ed
621 0ed56567 2020-11-06 op .Pp
622 eb699783 2021-01-18 op The following is an example of a possible configuration for a site
623 eb699783 2021-01-18 op that enables only TLSv1.3, adds a mime type for the file extension
624 eb699783 2021-01-18 op "rtf" and defines two virtual host:
625 eb699783 2021-01-18 op .Bd -literal -offset indent
626 eb699783 2021-01-18 op ipv6 on		# enable ipv6
627 eb699783 2021-01-18 op 
628 eb699783 2021-01-18 op protocols "tlsv1.3"
629 eb699783 2021-01-18 op 
630 d19951cf 2021-07-09 op map "application/rtf" to-ext "rtf"
631 eb699783 2021-01-18 op 
632 eb699783 2021-01-18 op server "example.com" {
633 eb699783 2021-01-18 op 	cert "/path/to/cert.pem"
634 eb699783 2021-01-18 op 	key  "/path/to/key.pem"
635 eb699783 2021-01-18 op 	root "/var/gemini/example.com"
636 eb699783 2021-01-18 op }
637 eb699783 2021-01-18 op 
638 eb699783 2021-01-18 op server "it.example.com" {
639 eb699783 2021-01-18 op 	cert "/path/to/cert.pem"
640 eb699783 2021-01-18 op 	key  "/path/to/key.pem"
641 eb699783 2021-01-18 op 	root "/var/gemini/it.example.com"
642 2b520ad5 2021-07-09 op 
643 2b520ad5 2021-07-09 op 	# enable cgi scripts inside "cgi-bin"
644 87f2b68b 2021-02-02 op 	cgi  "/cgi-bin/*"
645 2b520ad5 2021-07-09 op 
646 2b520ad5 2021-07-09 op 	# set the language for text/gemini files
647 de27389e 2021-01-21 op 	lang "it"
648 eb699783 2021-01-18 op }
649 eb699783 2021-01-18 op .Ed
650 f28d96d3 2021-01-25 op .Pp
651 f28d96d3 2021-01-25 op Yet another example, showing how to enable a
652 f28d96d3 2021-01-25 op .Ic chroot
653 f28d96d3 2021-01-25 op and use
654 f28d96d3 2021-01-25 op .Ic location
655 f28d96d3 2021-01-25 op rule
656 f28d96d3 2021-01-25 op .Bd -literal -offset indent
657 f28d96d3 2021-01-25 op chroot "/var/gemini"
658 f28d96d3 2021-01-25 op user "_gmid"
659 f28d96d3 2021-01-25 op 
660 f28d96d3 2021-01-25 op server "example.com" {
661 2b520ad5 2021-07-09 op 	cert "/path/to/cert.pem" # absolute path
662 2b520ad5 2021-07-09 op 	key  "/path/to/key.pem"  # also absolute
663 2b520ad5 2021-07-09 op 	root "/example.com"      # relative to the chroot
664 f28d96d3 2021-01-25 op 
665 4ee08bd1 2021-02-03 op 	location "/static/*" {
666 2b520ad5 2021-07-09 op 		# load the following rules only for
667 2b520ad5 2021-07-09 op 		# requests that matches "/static/*"
668 2b520ad5 2021-07-09 op 
669 f28d96d3 2021-01-25 op 		auto index on
670 f28d96d3 2021-01-25 op 		index "index.gemini"
671 f28d96d3 2021-01-25 op 	}
672 f28d96d3 2021-01-25 op }
673 f28d96d3 2021-01-25 op .Ed
674 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
675 ef04b551 2021-01-09 op .Nm
676 eb699783 2021-01-18 op uses the
677 eb699783 2021-01-18 op .Dq Flexible and Economical
678 eb699783 2021-01-18 op UTF-8 decoder written by
679 f28d96d3 2021-01-25 op .An Bjoern Hoehrmann .
680 714685c1 2021-01-30 op .Sh AUTHORS
681 714685c1 2021-01-30 op .An -nosplit
682 714685c1 2021-01-30 op The
683 714685c1 2021-01-30 op .Nm
684 714685c1 2021-01-30 op program was written by
685 714685c1 2021-01-30 op .An Omar Polo Aq Mt op@omarpolo.com .
686 3e4749f7 2020-10-02 op .Sh CAVEATS
687 3e4749f7 2020-10-02 op .Bl -bullet
688 3e4749f7 2020-10-02 op .It
689 2b520ad5 2021-07-09 op All the root directories are opened during the daemon startup; if a
690 2b520ad5 2021-07-09 op root directory is deleted and then re-created,
691 eb699783 2021-01-18 op .Nm
692 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
693 2b520ad5 2021-07-09 op This restriction only applies to the root directories and not their
694 2b520ad5 2021-07-09 op content.
695 043acc97 2020-12-25 op .It
696 714685c1 2021-01-30 op a %2F sequence is indistinguishable from a literal slash: this is not
697 714685c1 2021-01-30 op RFC3986-compliant.
698 00781742 2020-12-25 op .It
699 714685c1 2021-01-30 op a %00 sequence is treated as invalid character and thus rejected.
700 3e4749f7 2020-10-02 op .El