4 fab952e1 2020-10-03 op **gmid** - dead simple zero configuration gemini server
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*]
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.
23 3e4749f7 2020-10-02 op will strip any sequence of
27 a5d310bc 2020-11-10 op in the requests made by clients and will refuse to follow symlinks.
28 6980aad6 2020-10-02 op Furthermore, on
33 3e4749f7 2020-10-02 op are used to ensure that
35 92e66347 2020-11-06 op dosen't do anything else than read files from the given directory,
36 92e66347 2020-11-06 op accept network connections and, optionally, execute CGI scripts.
38 3e4749f7 2020-10-02 op It should be noted that
40 3e4749f7 2020-10-02 op is very simple in its implementation, and so it may not be appropriate
41 92e66347 2020-11-06 op for serving sites with lots of users.
42 92e66347 2020-11-06 op After all, the code is single threaded and use a single process,
43 83000e2d 2020-12-21 op although it can handle multiple clients at the same time.
45 fab952e1 2020-10-03 op If a user request path is a directory,
47 fab952e1 2020-10-03 op will try to serve a
49 fab952e1 2020-10-03 op file inside that directory.
51 3e4749f7 2020-10-02 op The options are as follows:
53 3e4749f7 2020-10-02 op **-c** *cert.pem*
55 3e4749f7 2020-10-02 op > The certificate to use, by default is
60 3e4749f7 2020-10-02 op > The root directory to serve.
62 a5d310bc 2020-11-10 op > won't serve any file that is outside that directory.
63 a5d310bc 2020-11-10 op > By default is
68 d7802bb4 2020-12-02 op > stays and log in the foreground, do not daemonize the process.
72 fab952e1 2020-10-03 op > Print the usage and exit.
74 3e4749f7 2020-10-02 op **-k** *key.pem*
76 3e4749f7 2020-10-02 op > The key for the certificate, by default is
81 721e2325 2020-11-18 op > The port to bind to, by default 1965.
85 0ed56567 2020-11-06 op > Enable execution of CGI scripts inside the given directory (relative
86 0ed56567 2020-11-06 op > to the document root.) Cannot be provided more than once.
90 0ed56567 2020-11-06 op When CGI scripts are enabled for a directory, a request for an
91 0ed56567 2020-11-06 op executable file will execute it and fed its output to the client.
93 92e66347 2020-11-06 op The CGI scripts will inherit the environment from
95 92e66347 2020-11-06 op with these additional variables set:
97 92e66347 2020-11-06 op `SERVER_SOFTWARE`
101 92e66347 2020-11-06 op `SERVER_PORT`
105 a5d310bc 2020-11-10 op `SCRIPT_NAME`
107 a5d310bc 2020-11-10 op > The (public) path to the script.
109 a5d310bc 2020-11-10 op `SCRIPT_EXECUTABLE`
111 a5d310bc 2020-11-10 op > The full path to the executable.
113 a5d310bc 2020-11-10 op `REQUEST_URI`
115 a5d310bc 2020-11-10 op > The user request (without the query parameters.)
117 a5d310bc 2020-11-10 op `REQUEST_RELATIVE`
119 a5d310bc 2020-11-10 op > The request relative to the script.
121 92e66347 2020-11-06 op `QUERY_STRING`
123 a5d310bc 2020-11-10 op > The query parameters.
125 a5d310bc 2020-11-10 op `REMOTE_HOST`
127 a5d310bc 2020-11-10 op > The remote IP address.
129 677afbd3 2020-12-02 op `REMOTE_ADDR`
131 677afbd3 2020-12-02 op > The remote IP address.
133 a5d310bc 2020-11-10 op `DOCUMENT_ROOT`
135 a5d310bc 2020-11-10 op > The root directory being served, the one provided with the
137 a5d310bc 2020-11-10 op > parameter to
142 677afbd3 2020-12-02 op > The string "Certificate" if the client used a certificate, otherwise unset.
144 677afbd3 2020-12-02 op `REMOTE_USER`
146 677afbd3 2020-12-02 op > The subject of the client certificate if provided, otherwise unset.
148 677afbd3 2020-12-02 op `TLS_CLIENT_ISSUER`
150 677afbd3 2020-12-02 op > The is the issuer of the client certificate if provided, otherwise unset.
152 677afbd3 2020-12-02 op `TLS_CLIENT_HASH`
154 677afbd3 2020-12-02 op > The hash of the client certificate if provided, otherwise unset.
155 677afbd3 2020-12-02 op > The format is "ALGO:HASH".
157 a5d310bc 2020-11-10 op Let's say you have a script in
158 a5d310bc 2020-11-10 op */cgi-bin/script*
159 a5d310bc 2020-11-10 op and the user request is
160 a5d310bc 2020-11-10 op */cgi-bin/script/foo/bar?quux*.
162 a5d310bc 2020-11-10 op `SCRIPT_NAME`
164 a5d310bc 2020-11-10 op */cgi-bin/script*,
165 a5d310bc 2020-11-10 op `SCRIPT_EXECUTABLE`
167 a5d310bc 2020-11-10 op *$DOCUMENT\_ROOT/cgi-bin/script*,
168 a5d310bc 2020-11-10 op `REQUEST_URI`
170 a5d310bc 2020-11-10 op */cgi-bin/script/foo/bar*,
171 a5d310bc 2020-11-10 op `REQUEST_RELATIVE`
173 a5d310bc 2020-11-10 op *foo/bar and*
174 a5d310bc 2020-11-10 op `QUERY_STRING`
180 3e4749f7 2020-10-02 op To quickly getting started
182 3e4749f7 2020-10-02 op $ # generate a cert and a key
183 3e4749f7 2020-10-02 op $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \
184 3e4749f7 2020-10-02 op -out cert.pem -days 365 -nodes
186 3e4749f7 2020-10-02 op $ cat <<EOF > docs/index.gmi
187 3e4749f7 2020-10-02 op # Hello world
188 3e4749f7 2020-10-02 op test paragraph...
190 3e4749f7 2020-10-02 op $ gmid -c cert.pem -k key.pem -d docs
192 92e66347 2020-11-06 op Now you can visit gemini://localhost/ with your preferred gemini
195 0ed56567 2020-11-06 op To add some CGI scripts, assuming a setup similar to the previous
196 92e66347 2020-11-06 op example, you can
198 0ed56567 2020-11-06 op $ mkdir docs/cgi-bin
199 0ed56567 2020-11-06 op $ cat <<EOF > docs/cgi-bin/hello-world
201 92e66347 2020-11-06 op printf "20 text/plain\r\n"
202 0ed56567 2020-11-06 op echo "hello world!"
204 92e66347 2020-11-06 op $ gmid -x cgi-bin
206 92e66347 2020-11-06 op Note that the argument to the
211 0ed56567 2020-11-06 op *docs/cgi-bin*,
212 a5d310bc 2020-11-10 op since it's relative to the document root.
216 fab952e1 2020-10-03 op * it doesn't support virtual hosts: the host part of the request URL is
217 3e4749f7 2020-10-02 op completely ignored.
219 043acc97 2020-12-25 op * a %2F sequence in the path part is indistinguishable from a literal
220 043acc97 2020-12-25 op slash: this is not RFC3986-compliant.
