1 
2 # NAME
3 
4 **gmid** - dead simple zero configuration gemini server
5 
6 # SYNOPSIS
7 
8 **gmid**
9 \[**-h**]
10 \[**-c** *cert.pem*]
11 \[**-d** *docs*]
12 \[**-k** *key.pem*]
13 \[**-l** *logfile*]
14 \[**-p** *port*]
15 \[**-x** *cgi-bin*]
16 
17 # DESCRIPTION
18 
19 **gmid**
20 is a very simple and minimal gemini server that can serve static files
21 and execute CGI scripts.
22 
23 **gmid**
24 will strip any sequence of
25 *../*
26 or trailing
27 *..*
28 in the requests made by clients and will refuse to follow symlinks.
29 Furthermore, on
30 OpenBSD,
31 pledge(2)
32 and
33 unveil(2)
34 are used to ensure that
35 **gmid**
36 dosen't do anything else than read files from the given directory,
37 accept network connections and, optionally, execute CGI scripts.
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 requests concurrently.
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 **-c** *cert.pem*
55 
56 > The certificate to use, by default is
57 > *cert.pem*.
58 
59 **-d** *docs*
60 
61 > The root directory to serve.
62 > **gmid**
63 > won't serve any file that is outside that directory.
64 > By default is
65 > *docs*.
66 
67 **-h**
68 
69 > Print the usage and exit.
70 
71 **-k** *key.pem*
72 
73 > The key for the certificate, by default is
74 > *key.pem*.
75 
76 **-l** *logfile*
77 
78 > log to the given file instead of the standard error.
79 
80 **-p** *port*
81 
82 > The port to bind to, by default 1965.
83 
84 **-x** *dir*
85 
86 > Enable execution of CGI scripts inside the given directory (relative
87 > to the document root.)  Cannot be provided more than once.
88 
89 # CGI
90 
91 When CGI scripts are enabled for a directory, a request for an
92 executable file will execute it and fed its output to the client.
93 
94 The CGI scripts will inherit the environment from
95 **gmid**
96 with these additional variables set:
97 
98 `SERVER_SOFTWARE`
99 
100 > "gmid"
101 
102 `SERVER_PORT`
103 
104 > "1965"
105 
106 `SCRIPT_NAME`
107 
108 > The (public) path to the script.
109 
110 `SCRIPT_EXECUTABLE`
111 
112 > The full path to the executable.
113 
114 `REQUEST_URI`
115 
116 > The user request (without the query parameters.)
117 
118 `REQUEST_RELATIVE`
119 
120 > The request relative to the script.
121 
122 `QUERY_STRING`
123 
124 > The query parameters.
125 
126 `REMOTE_HOST`
127 
128 > The remote IP address.
129 
130 `DOCUMENT_ROOT`
131 
132 > The root directory being served, the one provided with the
133 > *d*
134 > parameter to
135 > **gmid**
136 
137 Let's say you have a script in
138 */cgi-bin/script*
139 and the user request is
140 */cgi-bin/script/foo/bar?quux*.
141 Then
142 `SCRIPT_NAME`
143 will be
144 */cgi-bin/script*,
145 `SCRIPT_EXECUTABLE`
146 will be
147 *$DOCUMENT\_ROOT/cgi-bin/script*,
148 `REQUEST_URI`
149 will be
150 */cgi-bin/script/foo/bar*,
151 `REQUEST_RELATIVE`
152 will be
153 *foo/bar and*
154 `QUERY_STRING`
155 will be
156 *quux*.
157 
158 # EXAMPLES
159 
160 To quickly getting started
161 
162 	$ # generate a cert and a key
163 	$ openssl req -x509 -newkey rsa:4096 -keyout key.pem \
164 	        -out cert.pem -days 365 -nodes
165 	$ mkdir docs
166 	$ cat <<EOF > docs/index.gmi
167 	# Hello world
168 	test paragraph...
169 	EOF
170 	$ gmid -c cert.pem -k key.pem -d docs
171 
172 Now you can visit gemini://localhost/ with your preferred gemini
173 client.
174 
175 To add some CGI scripts, assuming a setup similar to the previous
176 example, you can
177 
178 	$ mkdir docs/cgi-bin
179 	$ cat <<EOF > docs/cgi-bin/hello-world
180 	#!/bin/sh
181 	printf "20 text/plain\r\n"
182 	echo "hello world!"
183 	EOF
184 	$ gmid -x cgi-bin
185 
186 Note that the argument to the
187 **-x**
188 option is
189 *cgi-bin*
190 and not
191 *docs/cgi-bin*,
192 since it's relative to the document root.
193 
194 # CAVEATS
195 
196 *	it doesn't support virtual hosts: the host part of the request URL is
197 	completely ignored.
198 
199 *	it doesn't fork in the background or anything like that.
200