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