1 3e4749f7 2020-10-02 op .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
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.
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 3e4749f7 2020-10-02 op .Dd $Mdocdate: October 2 2020$
19 fab952e1 2020-10-03 op .Nd dead simple zero configuration gemini server
24 15902770 2021-01-15 op .Op Fl c Ar config
27 15902770 2021-01-15 op .Op Fl C Ar cert
28 15902770 2021-01-15 op .Op Fl d Ar root
29 15902770 2021-01-15 op .Op Fl K Ar key
30 721e2325 2020-11-18 op .Op Fl p Ar port
31 eb699783 2021-01-18 op .Op Fl x Ar directory
33 3e4749f7 2020-10-02 op .Sh DESCRIPTION
35 b9220ca4 2021-01-11 op is a simple and minimal gemini server that can serve static files and
36 b9220ca4 2021-01-11 op execute CGI scripts.
37 eb699783 2021-01-18 op It can run without a configuration file with a limited set of features
39 eb699783 2021-01-18 op If a configuration file is given, no other flags shall be given,
44 df6ca41d 2020-12-25 op fully supports IRIs (Internationalized Resource Identifiers, see
47 eb699783 2021-01-18 op The options are as follows:
48 eb699783 2021-01-18 op .Bl -tag -width 12m
49 eb699783 2021-01-18 op .It Fl c Pa config
50 eb699783 2021-01-18 op Specifies the configuration file.
52 eb699783 2021-01-18 op Check that the configuration is valid, but don't start the server.
55 eb699783 2021-01-18 op If no configuration file is given,
57 eb699783 2021-01-18 op will look for the following option
58 3e4749f7 2020-10-02 op .Bl -tag -width 12m
61 eb699783 2021-01-18 op .It Fl C Pa file
62 eb699783 2021-01-18 op The certificate to use.
63 eb699783 2021-01-18 op .It Fl d Pa directory
64 3e4749f7 2020-10-02 op The root directory to serve.
66 eb699783 2021-01-18 op Stays and log in the foreground, do not daemonize the process.
68 fab952e1 2020-10-03 op Print the usage and exit.
69 eb699783 2021-01-18 op .It Fl K Pa file
70 eb699783 2021-01-18 op The key for the certificate.
71 721e2325 2020-11-18 op .It Fl p Ar port
72 eb699783 2021-01-18 op The port to listen on, by default 1965.
73 eb699783 2021-01-18 op .It Fl x Pa directory
74 eb699783 2021-01-18 op Enable execution of CGI scripts.
75 eb699783 2021-01-18 op See the description of the
78 eb699783 2021-01-18 op option in the section
80 eb699783 2021-01-18 op below to learn how
83 eb699783 2021-01-18 op Cannot be provided more than once.
85 eb699783 2021-01-18 op .Sh CONFIGURATION FILE
86 eb699783 2021-01-18 op The configuration file is divided into two sections:
87 eb699783 2021-01-18 op .Bl -tag -width xxxx
88 eb699783 2021-01-18 op .It Sy Global Options
89 eb699783 2021-01-18 op Global settings for
91 eb699783 2021-01-18 op .It Sy Servers
92 eb699783 2021-01-18 op Virtual hosts definition
95 eb699783 2021-01-18 op Within the sections, empty lines are ignored and comments can be put
96 eb699783 2021-01-18 op anywhere in the file using a hash mark
98 eb699783 2021-01-18 op and extend to the end of the current line.
99 eb699783 2021-01-18 op A boolean is either the symbol
103 eb699783 2021-01-18 op .Ss Global Options
104 eb699783 2021-01-18 op .Bl -tag -width 12m
105 eb699783 2021-01-18 op .It Ic daemon Ar bool
106 eb699783 2021-01-18 op Enable or disables the daemon mode.
107 eb699783 2021-01-18 op In daemon mode
109 eb699783 2021-01-18 op will log to syslog and fork in the background.
110 eb699783 2021-01-18 op By default is off.
111 eb699783 2021-01-18 op .It Ic ipv6 Ar bool
112 eb699783 2021-01-18 op Enable or disable IPv6 support.
113 eb699783 2021-01-18 op By default is off.
114 eb699783 2021-01-18 op .It Ic port Ar portno
115 eb699783 2021-01-18 op The port to listen on.
116 eb699783 2021-01-18 op By default is 1965.
117 eb699783 2021-01-18 op .It Ic protocols Ar string
118 eb699783 2021-01-18 op Specify the TLS protocols to enable.
120 eb699783 2021-01-18 op .Xr tls_config_parse_protocols 3
121 eb699783 2021-01-18 op for the valid protocol string values.
122 eb699783 2021-01-18 op By default, both TLSv1.3 and TLSv1.2 are used.
125 eb699783 2021-01-18 op to enable only TLSv1.3.
126 eb699783 2021-01-18 op .It Ic mime Ar mime-type Ar file-extension
127 eb699783 2021-01-18 op Add a mapping for the given
128 eb699783 2021-01-18 op .Ar file-extension
130 eb699783 2021-01-18 op .Ar mime-type .
131 eb699783 2021-01-18 op Both argument are strings.
134 eb699783 2021-01-18 op Every virtual host is defined by a
137 eb699783 2021-01-18 op .Bl -tag -width Ds
138 eb699783 2021-01-18 op .It Ic server Ar hostname Brq ...
139 de27389e 2021-01-21 op Match the server name using shell globbing rules. This can be an explicit name,
140 de27389e 2021-01-21 op .Ar www.example.com ,
141 de27389e 2021-01-21 op or a name including a wildcards,
142 de27389e 2021-01-21 op .Ar *.example.com .
145 eb699783 2021-01-18 op Followed by a block of options that is enclosed in curly brackets:
146 eb699783 2021-01-18 op .Bl -tag -width Ds
147 eb699783 2021-01-18 op .It Ic cert Pa file
148 eb699783 2021-01-18 op Path to the certificate to use for this server.
151 eb699783 2021-01-18 op should contain a PEM encoded certificate.
152 eb699783 2021-01-18 op This option is mandatory.
153 eb699783 2021-01-18 op .It Ic key Pa file
154 eb699783 2021-01-18 op Specify the private key to use for this server.
157 eb699783 2021-01-18 op should contain a PEM encoded private key.
158 eb699783 2021-01-18 op This option is mandatory.
159 eb699783 2021-01-18 op .It Ic root Pa directory
160 eb699783 2021-01-18 op Specify the root directory for this server.
161 eb699783 2021-01-18 op This option is mandatory.
162 eb699783 2021-01-18 op .It Ic cgi Pa path
163 eb699783 2021-01-18 op Enable the execution of CGI scripts if
165 eb699783 2021-01-18 op is a prefix of the user request string.
166 eb699783 2021-01-18 op An empty path "" will effectively enable the execution of any file
167 eb699783 2021-01-18 op with the executable bit set inside the root directory.
168 6119e13e 2021-01-19 op .It Ic default type Ar string
169 6119e13e 2021-01-19 op Set the default media type that is used if the media type for a
170 6119e13e 2021-01-19 op specified extension is not found.
171 6119e13e 2021-01-19 op If not specified, the
172 6119e13e 2021-01-19 op .Ic default type
174 6119e13e 2021-01-19 op .Dq application/octet-stream .
175 05c23a54 2021-01-19 op .It Ic lang Ar string
176 05c23a54 2021-01-19 op Specify the language tag for the text/gemini content served.
177 05c23a54 2021-01-19 op If not specified, no
179 05c23a54 2021-01-19 op parameter will be added in the response.
180 e7a2a99b 2021-01-24 op .It Ic index Ar string
181 e7a2a99b 2021-01-24 op Set the directory index file.
182 e7a2a99b 2021-01-24 op If not specified, it defaults to
183 e7a2a99b 2021-01-24 op .Pa index.gmi
184 c8b74339 2021-01-24 op .It Ic location Pa path Brq ...
185 c8b74339 2021-01-24 op Specify server configuration rules for a specific location.
188 c8b74339 2021-01-24 op argument will be matched against the request path with shell globbing
190 c8b74339 2021-01-24 op In case of multiple location statements in the same context, the last
191 c8b74339 2021-01-24 op matching location will be put into effect.
192 c8b74339 2021-01-24 op Therefore is advisable to match for a generic paths first and for more
193 c8b74339 2021-01-24 op specific ones later on.
196 c8b74339 2021-01-24 op section may include most of the server configuration rules
198 c8b74339 2021-01-24 op .Ic cert , Ic key , Ic root , Ic location No and Ic CGI .
201 0ed56567 2020-11-06 op When CGI scripts are enabled for a directory, a request for an
202 0ed56567 2020-11-06 op executable file will execute it and fed its output to the client.
204 a7b9bb4d 2021-01-24 op The CGI scripts are executed in the root directory of the virtual
205 a7b9bb4d 2021-01-24 op host, or in the served directory if run without config, and inherits
206 a7b9bb4d 2021-01-24 op the environment from
208 0ed56567 2020-11-06 op with these additional variables set:
209 a5d310bc 2020-11-10 op .Bl -tag -width 18m
210 28ec6178 2021-01-24 op .It Ev GATEWAY_INTERFACE
212 28ec6178 2021-01-24 op .It Ev SERVER_PROTOCOL
214 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
216 0ed56567 2020-11-06 op .It Ev SERVER_PORT
218 28ec6178 2021-01-24 op .It Ev SERVER_NAME
220 28ec6178 2021-01-24 op This variable is not available when operating without a configuration.
221 a5d310bc 2020-11-10 op .It Ev SCRIPT_NAME
222 28ec6178 2021-01-24 op The (public) path to the script, e.g.
223 28ec6178 2021-01-24 op .Pa "/cgi-bin/example.cgi"
224 a5d310bc 2020-11-10 op .It Ev SCRIPT_EXECUTABLE
225 a5d310bc 2020-11-10 op The full path to the executable.
226 a5d310bc 2020-11-10 op .It Ev REQUEST_URI
227 a5d310bc 2020-11-10 op The user request (without the query parameters.)
228 a5d310bc 2020-11-10 op .It Ev REQUEST_RELATIVE
229 a5d310bc 2020-11-10 op The request relative to the script.
230 0ed56567 2020-11-06 op .It Ev QUERY_STRING
231 a5d310bc 2020-11-10 op The query parameters.
232 a5d310bc 2020-11-10 op .It Ev REMOTE_HOST
233 a5d310bc 2020-11-10 op The remote IP address.
234 677afbd3 2020-12-02 op .It Ev REMOTE_ADDR
235 677afbd3 2020-12-02 op The remote IP address.
236 a5d310bc 2020-11-10 op .It Ev DOCUMENT_ROOT
237 a5d310bc 2020-11-10 op The root directory being served, the one provided with the
241 eb699783 2021-01-18 op or the root directory of the virtual host.
242 677afbd3 2020-12-02 op .It Ev AUTH_TYPE
243 28ec6178 2021-01-24 op The string "Certificate" if the client used a certificate, otherwise
245 677afbd3 2020-12-02 op .It Ev REMOTE_USER
246 677afbd3 2020-12-02 op The subject of the client certificate if provided, otherwise unset.
247 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_ISSUER
248 28ec6178 2021-01-24 op The is the issuer of the client certificate if provided, otherwise
250 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_HASH
251 677afbd3 2020-12-02 op The hash of the client certificate if provided, otherwise unset.
252 677afbd3 2020-12-02 op The format is "ALGO:HASH".
255 a5d310bc 2020-11-10 op Let's say you have a script in
256 a5d310bc 2020-11-10 op .Pa /cgi-bin/script
257 a5d310bc 2020-11-10 op and the user request is
258 a5d310bc 2020-11-10 op .Pa /cgi-bin/script/foo/bar?quux .
260 a5d310bc 2020-11-10 op .Ev SCRIPT_NAME
262 b9220ca4 2021-01-11 op .Pa cgi-bin/script ,
263 a5d310bc 2020-11-10 op .Ev SCRIPT_EXECUTABLE
265 a5d310bc 2020-11-10 op .Pa $DOCUMENT_ROOT/cgi-bin/script ,
266 a5d310bc 2020-11-10 op .Ev REQUEST_URI
268 b9220ca4 2021-01-11 op .Pa cgi-bin/script/foo/bar ,
269 a5d310bc 2020-11-10 op .Ev REQUEST_RELATIVE
273 a5d310bc 2020-11-10 op .Ev QUERY_STRING
277 3e4749f7 2020-10-02 op To quickly getting started
278 6980aad6 2020-10-02 op .Bd -literal -offset indent
279 3e4749f7 2020-10-02 op $ # generate a cert and a key
280 3e4749f7 2020-10-02 op $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
281 3e4749f7 2020-10-02 op -out cert.pem -days 365 -nodes
283 3e4749f7 2020-10-02 op $ cat <<EOF > docs/index.gmi
284 3e4749f7 2020-10-02 op # Hello world
285 3e4749f7 2020-10-02 op test paragraph...
287 de27389e 2021-01-21 op $ gmid -C cert.pem -K key.pem -d docs
290 0ed56567 2020-11-06 op Now you can visit gemini://localhost/ with your preferred gemini
293 0ed56567 2020-11-06 op To add some CGI scripts, assuming a setup similar to the previous
294 0ed56567 2020-11-06 op example, you can
295 0ed56567 2020-11-06 op .Bd -literal -offset indent
296 0ed56567 2020-11-06 op $ mkdir docs/cgi-bin
297 0ed56567 2020-11-06 op $ cat <<EOF > docs/cgi-bin/hello-world
299 0ed56567 2020-11-06 op printf "20 text/plain\\r\\n"
300 0ed56567 2020-11-06 op echo "hello world!"
302 de27389e 2021-01-21 op $ gmid -C cert.pem -K key.pem -d docs -x cgi-bin
305 0ed56567 2020-11-06 op Note that the argument to the
310 0ed56567 2020-11-06 op .Pa docs/cgi-bin ,
311 a5d310bc 2020-11-10 op since it's relative to the document root.
313 eb699783 2021-01-18 op The following is an example of a possible configuration for a site
314 eb699783 2021-01-18 op that enables only TLSv1.3, adds a mime type for the file extension
315 eb699783 2021-01-18 op "rtf" and defines two virtual host:
316 eb699783 2021-01-18 op .Bd -literal -offset indent
317 eb699783 2021-01-18 op ipv6 on # enable ipv6
318 eb699783 2021-01-18 op daemon on # enable daemon mode
320 eb699783 2021-01-18 op protocols "tlsv1.3"
322 eb699783 2021-01-18 op mime "application/rtf" "rtf"
324 eb699783 2021-01-18 op server "example.com" {
325 eb699783 2021-01-18 op cert "/path/to/cert.pem"
326 eb699783 2021-01-18 op key "/path/to/key.pem"
327 eb699783 2021-01-18 op root "/var/gemini/example.com"
330 eb699783 2021-01-18 op server "it.example.com" {
331 eb699783 2021-01-18 op cert "/path/to/cert.pem"
332 eb699783 2021-01-18 op key "/path/to/key.pem"
333 eb699783 2021-01-18 op root "/var/gemini/it.example.com"
334 eb699783 2021-01-18 op cgi "/cgi-bin"
338 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
341 eb699783 2021-01-18 op .Dq Flexible and Economical
342 eb699783 2021-01-18 op UTF-8 decoder written by
343 eb699783 2021-01-18 op .An Bjoern Hoehrmann
344 eb699783 2021-01-18 op for its IRI parser.
348 eb699783 2021-01-18 op The root directories of all virtual hosts are opened during the daemon
349 eb699783 2021-01-18 op startup; this means that if a root directory gets deleted and then
352 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
353 eb699783 2021-01-18 op This restriction applies only to the root directories and not their content.
355 043acc97 2020-12-25 op a %2F sequence in the path part is indistinguishable from a literal
356 043acc97 2020-12-25 op slash: this is not RFC3986-compliant.
358 00781742 2020-12-25 op a %00 sequence either in the path or in the query part is treated as
359 00781742 2020-12-25 op invalid character and thus rejected.
