1 3e4749f7 2020-10-02 op .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
3 3e4749f7 2020-10-02 op .\" Permission to use, copy, modify, and distribute this software for any
4 3e4749f7 2020-10-02 op .\" purpose with or without fee is hereby granted, provided that the above
5 3e4749f7 2020-10-02 op .\" copyright notice and this permission notice appear in all copies.
7 3e4749f7 2020-10-02 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 3e4749f7 2020-10-02 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 3e4749f7 2020-10-02 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 3e4749f7 2020-10-02 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 3e4749f7 2020-10-02 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 3e4749f7 2020-10-02 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 3e4749f7 2020-10-02 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 3e4749f7 2020-10-02 op .Dd $Mdocdate: October 2 2020$
19 fab952e1 2020-10-03 op .Nd dead simple zero configuration gemini server
24 3e4749f7 2020-10-02 op .Op Fl c Ar cert.pem
25 3e4749f7 2020-10-02 op .Op Fl d Ar docs
26 3e4749f7 2020-10-02 op .Op Fl k Ar key.pem
27 0ed56567 2020-11-06 op .Op Fl l Ar logfile
28 0ed56567 2020-11-06 op .Op Fl x Ar cgi-bin
30 3e4749f7 2020-10-02 op .Sh DESCRIPTION
32 0ed56567 2020-11-06 op is a very simple and minimal gemini server that can serve static files
33 0ed56567 2020-11-06 op and execute CGI scripts.
36 3e4749f7 2020-10-02 op will strip any sequence of
40 3e4749f7 2020-10-02 op in the requests made by clients, so it's impossible to serve content
43 0ed56567 2020-11-06 op directory by mistake, and will also refuse to follow symlinks.
44 6980aad6 2020-10-02 op Furthermore, on
49 3e4749f7 2020-10-02 op are used to ensure that
51 0ed56567 2020-11-06 op dosen't do anything else than read files from the given directory,
52 0ed56567 2020-11-06 op accept network connections and, optionally, execute CGI scripts.
54 3e4749f7 2020-10-02 op It should be noted that
56 3e4749f7 2020-10-02 op is very simple in its implementation, and so it may not be appropriate
57 0ed56567 2020-11-06 op for serving sites with lots of users.
58 0ed56567 2020-11-06 op After all, the code is single threaded and use a single process,
59 0ed56567 2020-11-06 op although it can handle multiple requests concurrently.
61 fab952e1 2020-10-03 op If a user request path is a directory,
63 fab952e1 2020-10-03 op will try to serve a
65 fab952e1 2020-10-03 op file inside that directory.
66 fab952e1 2020-10-03 op If not found, it will return an error 51 (not found) to the user.
68 3e4749f7 2020-10-02 op The options are as follows:
69 3e4749f7 2020-10-02 op .Bl -tag -width 12m
70 3e4749f7 2020-10-02 op .It Fl c Ar cert.pem
71 3e4749f7 2020-10-02 op The certificate to use, by default is
72 fab952e1 2020-10-03 op .Pa cert.pem .
73 3e4749f7 2020-10-02 op .It Fl d Ar docs
74 3e4749f7 2020-10-02 op The root directory to serve.
76 0ed56567 2020-11-06 op won't serve any file that is outside that directory, by default
79 fab952e1 2020-10-03 op Print the usage and exit.
80 3e4749f7 2020-10-02 op .It Fl k Ar key.pem
81 3e4749f7 2020-10-02 op The key for the certificate, by default is
83 0ed56567 2020-11-06 op .It Fl l Ar logfile
84 2c3a40fa 2020-11-06 op log to the given file instead of the standard error.
85 0ed56567 2020-11-06 op .It Fl x Ar dir
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.
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 0ed56567 2020-11-06 op The CGI scripts will inherit the environment from
95 0ed56567 2020-11-06 op with these additional variables set:
96 0ed56567 2020-11-06 op .Bl -tag -width 15m
97 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
99 0ed56567 2020-11-06 op .It Ev SERVER_PROTOCOL
101 0ed56567 2020-11-06 op .It Ev SERVER_PORT
103 0ed56567 2020-11-06 op .It Ev PATH_INFO
104 0ed56567 2020-11-06 op the request path
105 0ed56567 2020-11-06 op .It Ev PATH_TRANSLATED
106 0ed56567 2020-11-06 op the full path: the concatenation of the document root and the request
108 0ed56567 2020-11-06 op .It Ev QUERY_STRING
109 0ed56567 2020-11-06 op the query string if present in the request URL, otherwise it
110 0ed56567 2020-11-06 op won't be set.
111 0ed56567 2020-11-06 op .It Ev REMOTE_ADDR
112 0ed56567 2020-11-06 op the IP address of the client in dot notation
115 3e4749f7 2020-10-02 op To quickly getting started
116 6980aad6 2020-10-02 op .Bd -literal -offset indent
117 3e4749f7 2020-10-02 op $ # generate a cert and a key
118 3e4749f7 2020-10-02 op $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
119 3e4749f7 2020-10-02 op -out cert.pem -days 365 -nodes
121 3e4749f7 2020-10-02 op $ cat <<EOF > docs/index.gmi
122 3e4749f7 2020-10-02 op # Hello world
123 3e4749f7 2020-10-02 op test paragraph...
125 3e4749f7 2020-10-02 op $ gmid -c cert.pem -k key.pem -d docs
128 0ed56567 2020-11-06 op Now you can visit gemini://localhost/ with your preferred gemini
131 0ed56567 2020-11-06 op To add some CGI scripts, assuming a setup similar to the previous
132 0ed56567 2020-11-06 op example, you can
133 0ed56567 2020-11-06 op .Bd -literal -offset indent
134 0ed56567 2020-11-06 op $ mkdir docs/cgi-bin
135 0ed56567 2020-11-06 op $ cat <<EOF > docs/cgi-bin/hello-world
137 0ed56567 2020-11-06 op printf "20 text/plain\\r\\n"
138 0ed56567 2020-11-06 op echo "hello world!"
140 0ed56567 2020-11-06 op $ gmid -x cgi-bin
143 0ed56567 2020-11-06 op Note that the argument to the
148 0ed56567 2020-11-06 op .Pa docs/cgi-bin ,
149 0ed56567 2020-11-06 op since it’s relative to the document root.
153 fab952e1 2020-10-03 op it doesn't support virtual hosts: the host part of the request URL is
154 3e4749f7 2020-10-02 op completely ignored.
156 3e4749f7 2020-10-02 op it doesn't fork in the background or anything like that.