1 .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
2 .\"
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
6 .\"
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .Dd $Mdocdate: October 2 2020$
15 .Dt GMIND 1
16 .Os
17 .Sh NAME
18 .Nm gmid
19 .Nd dead simple zero configuration gemini server
20 .Sh SYNOPSIS
21 .Nm
22 .Bk -words
23 .Op Fl n
24 .Op Fl c Ar config
25 |
26 .Op Fl 6fh
27 .Op Fl C Ar cert
28 .Op Fl d Ar root
29 .Op Fl K Ar key
30 .Op Fl p Ar port
31 .Op Fl x Ar directory
32 .Ek
33 .Sh DESCRIPTION
34 .Nm
35 is a simple and minimal gemini server that can serve static files and
36 execute CGI scripts.
37 It can run without a configuration file with a limited set of features
38 available.
39 If a configuration file is given, no other flags shall be given,
40 except for
41 .Fl n .
42 .Pp
43 .Nm
44 fully supports IRIs (Internationalized Resource Identifiers, see
45 RFC3987).
46 .Pp
47 The options are as follows:
48 .Bl -tag -width 12m
49 .It Fl c Pa config
50 Specifies the configuration file.
51 .It Fl n
52 Check that the configuration is valid, but don't start the server.
53 .El
54 .Pp
55 If no configuration file is given,
56 .Nm
57 will look for the following option
58 .Bl -tag -width 12m
59 .It Fl 6
60 Enable IPv6.
61 .It Fl C Pa file
62 The certificate to use.
63 .It Fl d Pa directory
64 The root directory to serve.
65 .It Fl f
66 Stays and log in the foreground, do not daemonize the process.
67 .It Fl h
68 Print the usage and exit.
69 .It Fl K Pa file
70 The key for the certificate.
71 .It Fl p Ar port
72 The port to listen on, by default 1965.
73 .It Fl x Pa directory
74 Enable execution of CGI scripts.
75 See the description of the
76 .Ic cgi
77 .Ic server
78 option in the section
79 .Sq Servers
80 below to learn how
81 .Pa directory
82 is processed.
83 Cannot be provided more than once.
84 .El
85 .Sh CONFIGURATION FILE
86 The configuration file is divided into two sections:
87 .Bl -tag -width xxxx
88 .It Sy Global Options
89 Global settings for
90 .Nm .
91 .It Sy Servers
92 Virtual hosts definition
93 .El
94 .Pp
95 Within the sections, empty lines are ignored and comments can be put
96 anywhere in the file using a hash mark
97 .Pq Sq # ,
98 and extend to the end of the current line.
99 A boolean is either the symbol
100 .Sq on
101 or
102 .Sq off .
103 .Ss Global Options
104 .Bl -tag -width 12m
105 .It Ic daemon Ar bool
106 Enable or disables the daemon mode.
107 In daemon mode
108 .Nm
109 will log to syslog and fork in the background.
110 By default is off.
111 .It Ic ipv6 Ar bool
112 Enable or disable IPv6 support.
113 By default is off.
114 .It Ic port Ar portno
115 The port to listen on.
116 By default is 1965.
117 .It Ic protocols Ar string
118 Specify the TLS protocols to enable.
119 Refer to
120 .Xr tls_config_parse_protocols 3
121 for the valid protocol string values.
122 By default, both TLSv1.3 and TLSv1.2 are used.
123 Use
124 .Dq tlsv1.3
125 to enable only TLSv1.3.
126 .It Ic mime Ar mime-type Ar file-extension
127 Add a mapping for the given
128 .Ar file-extension
129 to the given
130 .Ar mime-type .
131 Both argument are strings.
132 .El
133 .Ss Servers
134 Every virtual host is defined by a
135 .Ic server
136 block:
137 .Bl -tag -width Ds
138 .It Ic server Ar hostname Brq ...
139 Match the server name using shell globbing rules.  This can be an explicit name,
140 .Ar www.example.com ,
141 or a name including a wildcards,
142 .Ar *.example.com .
143 .El
144 .Pp
145 Followed by a block of options that is enclosed in curly brackets:
146 .Bl -tag -width Ds
147 .It Ic cert Pa file
148 Path to the certificate to use for this server.
149 The
150 .Pa file
151 should contain a PEM encoded certificate.
152 This option is mandatory.
153 .It Ic key Pa file
154 Specify the private key to use for this server.
155 The
156 .Pa file
157 should contain a PEM encoded private key.
158 This option is mandatory.
159 .It Ic root Pa directory
160 Specify the root directory for this server.
161 This option is mandatory.
162 .It Ic cgi Pa path
163 Enable the execution of CGI scripts if
164 .Pa path
165 is a prefix of the user request string.
166 An empty path "" will effectively enable the execution of any file
167 with the executable bit set inside the root directory.
168 .It Ic default type Ar string
169 Set the default media type that is used if the media type for a
170 specified extension is not found.
171 If not specified, the
172 .Ic default type
173 is set to
174 .Dq application/octet-stream .
175 .It Ic lang Ar string
176 Specify the language tag for the text/gemini content served.
177 If not specified, no
178 .Dq lang
179 parameter will be added in the response.
180 .It Ic index Ar string
181 Set the directory index file.
182 If not specified, it defaults to
183 .Pa index.gmi
184 .El
185 .Sh CGI
186 When CGI scripts are enabled for a directory, a request for an
187 executable file will execute it and fed its output to the client.
188 .Pp
189 The CGI scripts are executed in the root directory of the virtual
190 host, or in the served directory if run without config, and inherits
191 the environment from
192 .Nm
193 with these additional variables set:
194 .Bl -tag -width 18m
195 .It Ev GATEWAY_INTERFACE
196 "CGI/1.1"
197 .It Ev SERVER_PROTOCOL
198 "GEMINI"
199 .It Ev SERVER_SOFTWARE
200 "gmid"
201 .It Ev SERVER_PORT
202 "1965"
203 .It Ev SERVER_NAME
204 The vhost.
205 This variable is not available when operating without a configuration.
206 .It Ev SCRIPT_NAME
207 The (public) path to the script, e.g.
208 .Pa "/cgi-bin/example.cgi"
209 .It Ev SCRIPT_EXECUTABLE
210 The full path to the executable.
211 .It Ev REQUEST_URI
212 The user request (without the query parameters.)
213 .It Ev REQUEST_RELATIVE
214 The request relative to the script.
215 .It Ev QUERY_STRING
216 The query parameters.
217 .It Ev REMOTE_HOST
218 The remote IP address.
219 .It Ev REMOTE_ADDR
220 The remote IP address.
221 .It Ev DOCUMENT_ROOT
222 The root directory being served, the one provided with the
223 .Ar d
224 parameter to
225 .Nm
226 or the root directory of the virtual host.
227 .It Ev AUTH_TYPE
228 The string "Certificate" if the client used a certificate, otherwise
229 unset.
230 .It Ev REMOTE_USER
231 The subject of the client certificate if provided, otherwise unset.
232 .It Ev TLS_CLIENT_ISSUER
233 The is the issuer of the client certificate if provided, otherwise
234 unset.
235 .It Ev TLS_CLIENT_HASH
236 The hash of the client certificate if provided, otherwise unset.
237 The format is "ALGO:HASH".
238 .El
239 .Pp
240 Let's say you have a script in
241 .Pa /cgi-bin/script
242 and the user request is
243 .Pa /cgi-bin/script/foo/bar?quux .
244 Then
245 .Ev SCRIPT_NAME
246 will be
247 .Pa cgi-bin/script ,
248 .Ev SCRIPT_EXECUTABLE
249 will be
250 .Pa $DOCUMENT_ROOT/cgi-bin/script ,
251 .Ev REQUEST_URI
252 will be
253 .Pa cgi-bin/script/foo/bar ,
254 .Ev REQUEST_RELATIVE
255 will be
256 .Pa foo/bar
257 and
258 .Ev QUERY_STRING
259 will be
260 .Ar quux .
261 .Sh EXAMPLES
262 To quickly getting started
263 .Bd -literal -offset indent
264 $ # generate a cert and a key
265 $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
266         -out cert.pem -days 365 -nodes
267 $ mkdir docs
268 $ cat <<EOF > docs/index.gmi
269 # Hello world
270 test paragraph...
271 EOF
272 $ gmid -C cert.pem -K key.pem -d docs
273 .Ed
274 .Pp
275 Now you can visit gemini://localhost/ with your preferred gemini
276 client.
277 .Pp
278 To add some CGI scripts, assuming a setup similar to the previous
279 example, you can
280 .Bd -literal -offset indent
281 $ mkdir docs/cgi-bin
282 $ cat <<EOF > docs/cgi-bin/hello-world
283 #!/bin/sh
284 printf "20 text/plain\\r\\n"
285 echo "hello world!"
286 EOF
287 $ gmid -C cert.pem -K key.pem -d docs -x cgi-bin
288 .Ed
289 .Pp
290 Note that the argument to the
291 .Fl x
292 option is
293 .Pa cgi-bin
294 and not
295 .Pa docs/cgi-bin ,
296 since it's relative to the document root.
297 .Pp
298 The following is an example of a possible configuration for a site
299 that enables only TLSv1.3, adds a mime type for the file extension
300 "rtf" and defines two virtual host:
301 .Bd -literal -offset indent
302 ipv6 on		# enable ipv6
303 daemon on	# enable daemon mode
304 
305 protocols "tlsv1.3"
306 
307 mime "application/rtf" "rtf"
308 
309 server "example.com" {
310 	cert "/path/to/cert.pem"
311 	key  "/path/to/key.pem"
312 	root "/var/gemini/example.com"
313 }
314 
315 server "it.example.com" {
316 	cert "/path/to/cert.pem"
317 	key  "/path/to/key.pem"
318 	root "/var/gemini/it.example.com"
319 	cgi  "/cgi-bin"
320 	lang "it"
321 }
322 .Ed
323 .Sh ACKNOWLEDGEMENTS
324 .Nm
325 uses the
326 .Dq Flexible and Economical
327 UTF-8 decoder written by
328 .An Bjoern Hoehrmann
329 for its IRI parser.
330 .Sh CAVEATS
331 .Bl -bullet
332 .It
333 The root directories of all virtual hosts are opened during the daemon
334 startup; this means that if a root directory gets deleted and then
335 re-created,
336 .Nm
337 won't be able to serve files inside that directory until a restart.
338 This restriction applies only to the root directories and not their content.
339 .It
340 a %2F sequence in the path part is indistinguishable from a literal
341 slash: this is not RFC3986-compliant.
342 .It
343 a %00 sequence either in the path or in the query part is treated as
344 invalid character and thus rejected.
345 .El