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 d7802bb4 2020-12-02 op \[**-fh**]
 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 3e4749f7 2020-10-02 op **-c** *cert.pem*
 55 3e4749f7 2020-10-02 op 
 56 3e4749f7 2020-10-02 op > The certificate to use, by default is
 57 fab952e1 2020-10-03 op > *cert.pem*.
 58 3e4749f7 2020-10-02 op 
 59 3e4749f7 2020-10-02 op **-d** *docs*
 60 3e4749f7 2020-10-02 op 
 61 3e4749f7 2020-10-02 op > The root directory to serve.
 62 3e4749f7 2020-10-02 op > **gmid**
 63 a5d310bc 2020-11-10 op > won't serve any file that is outside that directory.
 64 a5d310bc 2020-11-10 op > By default is
 65 92e66347 2020-11-06 op > *docs*.
 66 3e4749f7 2020-10-02 op 
 67 d7802bb4 2020-12-02 op **-f**
 68 d7802bb4 2020-12-02 op 
 69 d7802bb4 2020-12-02 op > stays and log in the foreground, do not daemonize the process.
 70 d7802bb4 2020-12-02 op 
 71 3e4749f7 2020-10-02 op **-h**
 72 3e4749f7 2020-10-02 op 
 73 fab952e1 2020-10-03 op > Print the usage and exit.
 74 3e4749f7 2020-10-02 op 
 75 3e4749f7 2020-10-02 op **-k** *key.pem*
 76 3e4749f7 2020-10-02 op 
 77 3e4749f7 2020-10-02 op > The key for the certificate, by default is
 78 fab952e1 2020-10-03 op > *key.pem*.
 79 3e4749f7 2020-10-02 op 
 80 721e2325 2020-11-18 op **-p** *port*
 81 721e2325 2020-11-18 op 
 82 721e2325 2020-11-18 op > The port to bind to, by default 1965.
 83 721e2325 2020-11-18 op 
 84 0ed56567 2020-11-06 op **-x** *dir*
 85 72342dc9 2020-11-06 op 
 86 0ed56567 2020-11-06 op > Enable execution of CGI scripts inside the given directory (relative
 87 0ed56567 2020-11-06 op > to the document root.)  Cannot be provided more than once.
 88 72342dc9 2020-11-06 op 
 89 72342dc9 2020-11-06 op # CGI
 90 72342dc9 2020-11-06 op 
 91 0ed56567 2020-11-06 op When CGI scripts are enabled for a directory, a request for an
 92 0ed56567 2020-11-06 op executable file will execute it and fed its output to the client.
 93 72342dc9 2020-11-06 op 
 94 92e66347 2020-11-06 op The CGI scripts will inherit the environment from
 95 92e66347 2020-11-06 op **gmid**
 96 92e66347 2020-11-06 op with these additional variables set:
 97 92e66347 2020-11-06 op 
 98 92e66347 2020-11-06 op `SERVER_SOFTWARE`
 99 92e66347 2020-11-06 op 
100 92e66347 2020-11-06 op > "gmid"
101 92e66347 2020-11-06 op 
102 92e66347 2020-11-06 op `SERVER_PORT`
103 92e66347 2020-11-06 op 
104 92e66347 2020-11-06 op > "1965"
105 92e66347 2020-11-06 op 
106 a5d310bc 2020-11-10 op `SCRIPT_NAME`
107 92e66347 2020-11-06 op 
108 a5d310bc 2020-11-10 op > The (public) path to the script.
109 92e66347 2020-11-06 op 
110 a5d310bc 2020-11-10 op `SCRIPT_EXECUTABLE`
111 92e66347 2020-11-06 op 
112 a5d310bc 2020-11-10 op > The full path to the executable.
113 92e66347 2020-11-06 op 
114 a5d310bc 2020-11-10 op `REQUEST_URI`
115 a5d310bc 2020-11-10 op 
116 a5d310bc 2020-11-10 op > The user request (without the query parameters.)
117 a5d310bc 2020-11-10 op 
118 a5d310bc 2020-11-10 op `REQUEST_RELATIVE`
119 a5d310bc 2020-11-10 op 
120 a5d310bc 2020-11-10 op > The request relative to the script.
121 a5d310bc 2020-11-10 op 
122 92e66347 2020-11-06 op `QUERY_STRING`
123 92e66347 2020-11-06 op 
124 a5d310bc 2020-11-10 op > The query parameters.
125 92e66347 2020-11-06 op 
126 a5d310bc 2020-11-10 op `REMOTE_HOST`
127 92e66347 2020-11-06 op 
128 a5d310bc 2020-11-10 op > The remote IP address.
129 92e66347 2020-11-06 op 
130 677afbd3 2020-12-02 op `REMOTE_ADDR`
131 677afbd3 2020-12-02 op 
132 677afbd3 2020-12-02 op > The remote IP address.
133 677afbd3 2020-12-02 op 
134 a5d310bc 2020-11-10 op `DOCUMENT_ROOT`
135 a5d310bc 2020-11-10 op 
136 a5d310bc 2020-11-10 op > The root directory being served, the one provided with the
137 a5d310bc 2020-11-10 op > *d*
138 a5d310bc 2020-11-10 op > parameter to
139 a5d310bc 2020-11-10 op > **gmid**
140 a5d310bc 2020-11-10 op 
141 677afbd3 2020-12-02 op `AUTH_TYPE`
142 677afbd3 2020-12-02 op 
143 677afbd3 2020-12-02 op > The string "Certificate" if the client used a certificate, otherwise unset.
144 677afbd3 2020-12-02 op 
145 677afbd3 2020-12-02 op `REMOTE_USER`
146 677afbd3 2020-12-02 op 
147 677afbd3 2020-12-02 op > The subject of the client certificate if provided, otherwise unset.
148 677afbd3 2020-12-02 op 
149 677afbd3 2020-12-02 op `TLS_CLIENT_ISSUER`
150 677afbd3 2020-12-02 op 
151 677afbd3 2020-12-02 op > The is the issuer of the client certificate if provided, otherwise unset.
152 677afbd3 2020-12-02 op 
153 677afbd3 2020-12-02 op `TLS_CLIENT_HASH`
154 677afbd3 2020-12-02 op 
155 677afbd3 2020-12-02 op > The hash of the client certificate if provided, otherwise unset.
156 677afbd3 2020-12-02 op > The format is "ALGO:HASH".
157 677afbd3 2020-12-02 op 
158 a5d310bc 2020-11-10 op Let's say you have a script in
159 a5d310bc 2020-11-10 op */cgi-bin/script*
160 a5d310bc 2020-11-10 op and the user request is
161 a5d310bc 2020-11-10 op */cgi-bin/script/foo/bar?quux*.
162 a5d310bc 2020-11-10 op Then
163 a5d310bc 2020-11-10 op `SCRIPT_NAME`
164 a5d310bc 2020-11-10 op will be
165 a5d310bc 2020-11-10 op */cgi-bin/script*,
166 a5d310bc 2020-11-10 op `SCRIPT_EXECUTABLE`
167 a5d310bc 2020-11-10 op will be
168 a5d310bc 2020-11-10 op *$DOCUMENT\_ROOT/cgi-bin/script*,
169 a5d310bc 2020-11-10 op `REQUEST_URI`
170 a5d310bc 2020-11-10 op will be
171 a5d310bc 2020-11-10 op */cgi-bin/script/foo/bar*,
172 a5d310bc 2020-11-10 op `REQUEST_RELATIVE`
173 a5d310bc 2020-11-10 op will be
174 a5d310bc 2020-11-10 op *foo/bar and*
175 a5d310bc 2020-11-10 op `QUERY_STRING`
176 a5d310bc 2020-11-10 op will be
177 a5d310bc 2020-11-10 op *quux*.
178 a5d310bc 2020-11-10 op 
179 3e4749f7 2020-10-02 op # EXAMPLES
180 3e4749f7 2020-10-02 op 
181 3e4749f7 2020-10-02 op To quickly getting started
182 3e4749f7 2020-10-02 op 
183 3e4749f7 2020-10-02 op 	$ # generate a cert and a key
184 3e4749f7 2020-10-02 op 	$ openssl req -x509 -newkey rsa:4096 -keyout key.pem \
185 3e4749f7 2020-10-02 op 	        -out cert.pem -days 365 -nodes
186 3e4749f7 2020-10-02 op 	$ mkdir docs
187 3e4749f7 2020-10-02 op 	$ cat <<EOF > docs/index.gmi
188 3e4749f7 2020-10-02 op 	# Hello world
189 3e4749f7 2020-10-02 op 	test paragraph...
190 3e4749f7 2020-10-02 op 	EOF
191 3e4749f7 2020-10-02 op 	$ gmid -c cert.pem -k key.pem -d docs
192 3e4749f7 2020-10-02 op 
193 92e66347 2020-11-06 op Now you can visit gemini://localhost/ with your preferred gemini
194 0ed56567 2020-11-06 op client.
195 3e4749f7 2020-10-02 op 
196 0ed56567 2020-11-06 op To add some CGI scripts, assuming a setup similar to the previous
197 92e66347 2020-11-06 op example, you can
198 0ed56567 2020-11-06 op 
199 0ed56567 2020-11-06 op 	$ mkdir docs/cgi-bin
200 0ed56567 2020-11-06 op 	$ cat <<EOF > docs/cgi-bin/hello-world
201 0ed56567 2020-11-06 op 	#!/bin/sh
202 92e66347 2020-11-06 op 	printf "20 text/plain\r\n"
203 0ed56567 2020-11-06 op 	echo "hello world!"
204 0ed56567 2020-11-06 op 	EOF
205 92e66347 2020-11-06 op 	$ gmid -x cgi-bin
206 0ed56567 2020-11-06 op 
207 92e66347 2020-11-06 op Note that the argument to the
208 0ed56567 2020-11-06 op **-x**
209 0ed56567 2020-11-06 op option is
210 0ed56567 2020-11-06 op *cgi-bin*
211 0ed56567 2020-11-06 op and not
212 0ed56567 2020-11-06 op *docs/cgi-bin*,
213 a5d310bc 2020-11-10 op since it's relative to the document root.
214 0ed56567 2020-11-06 op 
215 ef04b551 2021-01-09 op # ACKNOWLEDGEMENTS
216 ef04b551 2021-01-09 op 
217 ef04b551 2021-01-09 op **gmid**
218 ef04b551 2021-01-09 op uses the "Flexible and Economical" UTF-8 decoder written by
219 ef04b551 2021-01-09 op Bjoern Hoehrmann.
220 ef04b551 2021-01-09 op 
221 3e4749f7 2020-10-02 op # CAVEATS
222 3e4749f7 2020-10-02 op 
223 fab952e1 2020-10-03 op *	it doesn't support virtual hosts: the host part of the request URL is
224 3e4749f7 2020-10-02 op 	completely ignored.
225 3e4749f7 2020-10-02 op 
226 043acc97 2020-12-25 op *	a %2F sequence in the path part is indistinguishable from a literal
227 043acc97 2020-12-25 op 	slash: this is not RFC3986-compliant.
228 043acc97 2020-12-25 op 
229 00781742 2020-12-25 op *	a %00 sequence either in the path or in the query part is treated as
230 00781742 2020-12-25 op 	invalid character and thus rejected.
231 00781742 2020-12-25 op