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