1 3e4749f7 2020-10-02 op 
  2 3e4749f7 2020-10-02 op # NAME
  3 3e4749f7 2020-10-02 op 
  4 fab952e1 2020-10-03 op **gmid** - dead simple zero configuration gemini server
  5 3e4749f7 2020-10-02 op 
  6 3e4749f7 2020-10-02 op # SYNOPSIS
  7 3e4749f7 2020-10-02 op 
  8 3e4749f7 2020-10-02 op **gmid**
  9 85dff1f9 2021-01-11 op \[**-6fh**]
 10 3e4749f7 2020-10-02 op \[**-c** *cert.pem*]
 11 3e4749f7 2020-10-02 op \[**-d** *docs*]
 12 3e4749f7 2020-10-02 op \[**-k** *key.pem*]
 13 721e2325 2020-11-18 op \[**-p** *port*]
 14 92e66347 2020-11-06 op \[**-x** *cgi-bin*]
 15 3e4749f7 2020-10-02 op 
 16 3e4749f7 2020-10-02 op # DESCRIPTION
 17 3e4749f7 2020-10-02 op 
 18 3e4749f7 2020-10-02 op **gmid**
 19 92e66347 2020-11-06 op is a very simple and minimal gemini server that can serve static files
 20 92e66347 2020-11-06 op and execute CGI scripts.
 21 3e4749f7 2020-10-02 op 
 22 3e4749f7 2020-10-02 op **gmid**
 23 df6ca41d 2020-12-25 op won't serve files outside the given directory and won't follow
 24 df6ca41d 2020-12-25 op symlinks.
 25 6980aad6 2020-10-02 op Furthermore, on
 26 6980aad6 2020-10-02 op OpenBSD,
 27 6980aad6 2020-10-02 op pledge(2)
 28 3e4749f7 2020-10-02 op and
 29 6980aad6 2020-10-02 op unveil(2)
 30 3e4749f7 2020-10-02 op are used to ensure that
 31 3e4749f7 2020-10-02 op **gmid**
 32 92e66347 2020-11-06 op dosen't do anything else than read files from the given directory,
 33 92e66347 2020-11-06 op accept network connections and, optionally, execute CGI scripts.
 34 3e4749f7 2020-10-02 op 
 35 df6ca41d 2020-12-25 op **gmid**
 36 df6ca41d 2020-12-25 op fully supports IRIs (Internationalized Resource Identifiers, see
 37 df6ca41d 2020-12-25 op RFC3987).
 38 df6ca41d 2020-12-25 op 
 39 3e4749f7 2020-10-02 op It should be noted that
 40 3e4749f7 2020-10-02 op **gmid**
 41 3e4749f7 2020-10-02 op is very simple in its implementation, and so it may not be appropriate
 42 92e66347 2020-11-06 op for serving sites with lots of users.
 43 92e66347 2020-11-06 op After all, the code is single threaded and use a single process,
 44 83000e2d 2020-12-21 op although it can handle multiple clients at the same time.
 45 3e4749f7 2020-10-02 op 
 46 fab952e1 2020-10-03 op If a user request path is a directory,
 47 fab952e1 2020-10-03 op **gmid**
 48 fab952e1 2020-10-03 op will try to serve a
 49 fab952e1 2020-10-03 op *index.gmi*
 50 fab952e1 2020-10-03 op file inside that directory.
 51 fab952e1 2020-10-03 op 
 52 3e4749f7 2020-10-02 op The options are as follows:
 53 3e4749f7 2020-10-02 op 
 54 85dff1f9 2021-01-11 op **-6**
 55 85dff1f9 2021-01-11 op 
 56 85dff1f9 2021-01-11 op > Enable IPv6.
 57 85dff1f9 2021-01-11 op 
 58 3e4749f7 2020-10-02 op **-c** *cert.pem*
 59 3e4749f7 2020-10-02 op 
 60 3e4749f7 2020-10-02 op > The certificate to use, by default is
 61 fab952e1 2020-10-03 op > *cert.pem*.
 62 3e4749f7 2020-10-02 op 
 63 3e4749f7 2020-10-02 op **-d** *docs*
 64 3e4749f7 2020-10-02 op 
 65 3e4749f7 2020-10-02 op > The root directory to serve.
 66 3e4749f7 2020-10-02 op > **gmid**
 67 a5d310bc 2020-11-10 op > won't serve any file that is outside that directory.
 68 a5d310bc 2020-11-10 op > By default is
 69 92e66347 2020-11-06 op > *docs*.
 70 3e4749f7 2020-10-02 op 
 71 d7802bb4 2020-12-02 op **-f**
 72 d7802bb4 2020-12-02 op 
 73 d7802bb4 2020-12-02 op > stays and log in the foreground, do not daemonize the process.
 74 d7802bb4 2020-12-02 op 
 75 3e4749f7 2020-10-02 op **-h**
 76 3e4749f7 2020-10-02 op 
 77 fab952e1 2020-10-03 op > Print the usage and exit.
 78 3e4749f7 2020-10-02 op 
 79 3e4749f7 2020-10-02 op **-k** *key.pem*
 80 3e4749f7 2020-10-02 op 
 81 3e4749f7 2020-10-02 op > The key for the certificate, by default is
 82 fab952e1 2020-10-03 op > *key.pem*.
 83 3e4749f7 2020-10-02 op 
 84 721e2325 2020-11-18 op **-p** *port*
 85 721e2325 2020-11-18 op 
 86 721e2325 2020-11-18 op > The port to bind to, by default 1965.
 87 721e2325 2020-11-18 op 
 88 0ed56567 2020-11-06 op **-x** *dir*
 89 72342dc9 2020-11-06 op 
 90 0ed56567 2020-11-06 op > Enable execution of CGI scripts inside the given directory (relative
 91 0ed56567 2020-11-06 op > to the document root.)  Cannot be provided more than once.
 92 72342dc9 2020-11-06 op 
 93 72342dc9 2020-11-06 op # CGI
 94 72342dc9 2020-11-06 op 
 95 0ed56567 2020-11-06 op When CGI scripts are enabled for a directory, a request for an
 96 0ed56567 2020-11-06 op executable file will execute it and fed its output to the client.
 97 72342dc9 2020-11-06 op 
 98 92e66347 2020-11-06 op The CGI scripts will inherit the environment from
 99 92e66347 2020-11-06 op **gmid**
100 92e66347 2020-11-06 op with these additional variables set:
101 92e66347 2020-11-06 op 
102 92e66347 2020-11-06 op `SERVER_SOFTWARE`
103 92e66347 2020-11-06 op 
104 92e66347 2020-11-06 op > "gmid"
105 92e66347 2020-11-06 op 
106 92e66347 2020-11-06 op `SERVER_PORT`
107 92e66347 2020-11-06 op 
108 92e66347 2020-11-06 op > "1965"
109 92e66347 2020-11-06 op 
110 a5d310bc 2020-11-10 op `SCRIPT_NAME`
111 92e66347 2020-11-06 op 
112 a5d310bc 2020-11-10 op > The (public) path to the script.
113 92e66347 2020-11-06 op 
114 a5d310bc 2020-11-10 op `SCRIPT_EXECUTABLE`
115 92e66347 2020-11-06 op 
116 a5d310bc 2020-11-10 op > The full path to the executable.
117 92e66347 2020-11-06 op 
118 a5d310bc 2020-11-10 op `REQUEST_URI`
119 a5d310bc 2020-11-10 op 
120 a5d310bc 2020-11-10 op > The user request (without the query parameters.)
121 a5d310bc 2020-11-10 op 
122 a5d310bc 2020-11-10 op `REQUEST_RELATIVE`
123 a5d310bc 2020-11-10 op 
124 a5d310bc 2020-11-10 op > The request relative to the script.
125 a5d310bc 2020-11-10 op 
126 92e66347 2020-11-06 op `QUERY_STRING`
127 92e66347 2020-11-06 op 
128 a5d310bc 2020-11-10 op > The query parameters.
129 92e66347 2020-11-06 op 
130 a5d310bc 2020-11-10 op `REMOTE_HOST`
131 92e66347 2020-11-06 op 
132 a5d310bc 2020-11-10 op > The remote IP address.
133 92e66347 2020-11-06 op 
134 677afbd3 2020-12-02 op `REMOTE_ADDR`
135 677afbd3 2020-12-02 op 
136 677afbd3 2020-12-02 op > The remote IP address.
137 677afbd3 2020-12-02 op 
138 a5d310bc 2020-11-10 op `DOCUMENT_ROOT`
139 a5d310bc 2020-11-10 op 
140 a5d310bc 2020-11-10 op > The root directory being served, the one provided with the
141 a5d310bc 2020-11-10 op > *d*
142 a5d310bc 2020-11-10 op > parameter to
143 a5d310bc 2020-11-10 op > **gmid**
144 a5d310bc 2020-11-10 op 
145 677afbd3 2020-12-02 op `AUTH_TYPE`
146 677afbd3 2020-12-02 op 
147 677afbd3 2020-12-02 op > The string "Certificate" if the client used a certificate, otherwise unset.
148 677afbd3 2020-12-02 op 
149 677afbd3 2020-12-02 op `REMOTE_USER`
150 677afbd3 2020-12-02 op 
151 677afbd3 2020-12-02 op > The subject of the client certificate if provided, otherwise unset.
152 677afbd3 2020-12-02 op 
153 677afbd3 2020-12-02 op `TLS_CLIENT_ISSUER`
154 677afbd3 2020-12-02 op 
155 677afbd3 2020-12-02 op > The is the issuer of the client certificate if provided, otherwise unset.
156 677afbd3 2020-12-02 op 
157 677afbd3 2020-12-02 op `TLS_CLIENT_HASH`
158 677afbd3 2020-12-02 op 
159 677afbd3 2020-12-02 op > The hash of the client certificate if provided, otherwise unset.
160 677afbd3 2020-12-02 op > The format is "ALGO:HASH".
161 677afbd3 2020-12-02 op 
162 a5d310bc 2020-11-10 op Let's say you have a script in
163 a5d310bc 2020-11-10 op */cgi-bin/script*
164 a5d310bc 2020-11-10 op and the user request is
165 a5d310bc 2020-11-10 op */cgi-bin/script/foo/bar?quux*.
166 a5d310bc 2020-11-10 op Then
167 a5d310bc 2020-11-10 op `SCRIPT_NAME`
168 a5d310bc 2020-11-10 op will be
169 a5d310bc 2020-11-10 op */cgi-bin/script*,
170 a5d310bc 2020-11-10 op `SCRIPT_EXECUTABLE`
171 a5d310bc 2020-11-10 op will be
172 a5d310bc 2020-11-10 op *$DOCUMENT\_ROOT/cgi-bin/script*,
173 a5d310bc 2020-11-10 op `REQUEST_URI`
174 a5d310bc 2020-11-10 op will be
175 a5d310bc 2020-11-10 op */cgi-bin/script/foo/bar*,
176 a5d310bc 2020-11-10 op `REQUEST_RELATIVE`
177 a5d310bc 2020-11-10 op will be
178 a5d310bc 2020-11-10 op *foo/bar and*
179 a5d310bc 2020-11-10 op `QUERY_STRING`
180 a5d310bc 2020-11-10 op will be
181 a5d310bc 2020-11-10 op *quux*.
182 a5d310bc 2020-11-10 op 
183 3e4749f7 2020-10-02 op # EXAMPLES
184 3e4749f7 2020-10-02 op 
185 3e4749f7 2020-10-02 op To quickly getting started
186 3e4749f7 2020-10-02 op 
187 3e4749f7 2020-10-02 op 	$ # generate a cert and a key
188 3e4749f7 2020-10-02 op 	$ openssl req -x509 -newkey rsa:4096 -keyout key.pem \
189 3e4749f7 2020-10-02 op 	        -out cert.pem -days 365 -nodes
190 3e4749f7 2020-10-02 op 	$ mkdir docs
191 3e4749f7 2020-10-02 op 	$ cat <<EOF > docs/index.gmi
192 3e4749f7 2020-10-02 op 	# Hello world
193 3e4749f7 2020-10-02 op 	test paragraph...
194 3e4749f7 2020-10-02 op 	EOF
195 3e4749f7 2020-10-02 op 	$ gmid -c cert.pem -k key.pem -d docs
196 3e4749f7 2020-10-02 op 
197 92e66347 2020-11-06 op Now you can visit gemini://localhost/ with your preferred gemini
198 0ed56567 2020-11-06 op client.
199 3e4749f7 2020-10-02 op 
200 0ed56567 2020-11-06 op To add some CGI scripts, assuming a setup similar to the previous
201 92e66347 2020-11-06 op example, you can
202 0ed56567 2020-11-06 op 
203 0ed56567 2020-11-06 op 	$ mkdir docs/cgi-bin
204 0ed56567 2020-11-06 op 	$ cat <<EOF > docs/cgi-bin/hello-world
205 0ed56567 2020-11-06 op 	#!/bin/sh
206 92e66347 2020-11-06 op 	printf "20 text/plain\r\n"
207 0ed56567 2020-11-06 op 	echo "hello world!"
208 0ed56567 2020-11-06 op 	EOF
209 92e66347 2020-11-06 op 	$ gmid -x cgi-bin
210 0ed56567 2020-11-06 op 
211 92e66347 2020-11-06 op Note that the argument to the
212 0ed56567 2020-11-06 op **-x**
213 0ed56567 2020-11-06 op option is
214 0ed56567 2020-11-06 op *cgi-bin*
215 0ed56567 2020-11-06 op and not
216 0ed56567 2020-11-06 op *docs/cgi-bin*,
217 a5d310bc 2020-11-10 op since it's relative to the document root.
218 0ed56567 2020-11-06 op 
219 ef04b551 2021-01-09 op # ACKNOWLEDGEMENTS
220 ef04b551 2021-01-09 op 
221 ef04b551 2021-01-09 op **gmid**
222 ef04b551 2021-01-09 op uses the "Flexible and Economical" UTF-8 decoder written by
223 ef04b551 2021-01-09 op Bjoern Hoehrmann.
224 ef04b551 2021-01-09 op 
225 3e4749f7 2020-10-02 op # CAVEATS
226 3e4749f7 2020-10-02 op 
227 fab952e1 2020-10-03 op *	it doesn't support virtual hosts: the host part of the request URL is
228 3e4749f7 2020-10-02 op 	completely ignored.
229 3e4749f7 2020-10-02 op 
230 043acc97 2020-12-25 op *	a %2F sequence in the path part is indistinguishable from a literal
231 043acc97 2020-12-25 op 	slash: this is not RFC3986-compliant.
232 043acc97 2020-12-25 op 
233 00781742 2020-12-25 op *	a %00 sequence either in the path or in the query part is treated as
234 00781742 2020-12-25 op 	invalid character and thus rejected.
235 00781742 2020-12-25 op