1 3e4749f7 2020-10-02 op .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
  2 3e4749f7 2020-10-02 op .\"
  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.
  6 3e4749f7 2020-10-02 op .\"
  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$
 15 3e4749f7 2020-10-02 op .Dt GMIND 1
 16 3e4749f7 2020-10-02 op .Os
 17 3e4749f7 2020-10-02 op .Sh NAME
 18 3e4749f7 2020-10-02 op .Nm gmid
 19 fab952e1 2020-10-03 op .Nd dead simple zero configuration gemini server
 20 3e4749f7 2020-10-02 op .Sh SYNOPSIS
 21 3e4749f7 2020-10-02 op .Nm
 22 3e4749f7 2020-10-02 op .Bk -words
 23 d7802bb4 2020-12-02 op .Op Fl fh
 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 721e2325 2020-11-18 op .Op Fl p Ar port
 28 0ed56567 2020-11-06 op .Op Fl x Ar cgi-bin
 29 3e4749f7 2020-10-02 op .Ek
 30 3e4749f7 2020-10-02 op .Sh DESCRIPTION
 31 3e4749f7 2020-10-02 op .Nm
 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.
 34 3e4749f7 2020-10-02 op .Pp
 35 3e4749f7 2020-10-02 op .Nm
 36 3e4749f7 2020-10-02 op will strip any sequence of
 37 3e4749f7 2020-10-02 op .Pa ../
 38 3e4749f7 2020-10-02 op or trailing
 39 3e4749f7 2020-10-02 op .Pa ..
 40 a5d310bc 2020-11-10 op in the requests made by clients and will refuse to follow symlinks.
 41 6980aad6 2020-10-02 op Furthermore, on
 42 6980aad6 2020-10-02 op .Ox ,
 43 6980aad6 2020-10-02 op .Xr pledge 2
 44 3e4749f7 2020-10-02 op and
 45 6980aad6 2020-10-02 op .Xr unveil 2
 46 3e4749f7 2020-10-02 op are used to ensure that
 47 3e4749f7 2020-10-02 op .Nm
 48 0ed56567 2020-11-06 op dosen't do anything else than read files from the given directory,
 49 0ed56567 2020-11-06 op accept network connections and, optionally, execute CGI scripts.
 50 3e4749f7 2020-10-02 op .Pp
 51 3e4749f7 2020-10-02 op It should be noted that
 52 3e4749f7 2020-10-02 op .Nm
 53 3e4749f7 2020-10-02 op is very simple in its implementation, and so it may not be appropriate
 54 0ed56567 2020-11-06 op for serving sites with lots of users.
 55 0ed56567 2020-11-06 op After all, the code is single threaded and use a single process,
 56 83000e2d 2020-12-21 op although it can handle multiple clients at the same time.
 57 3e4749f7 2020-10-02 op .Pp
 58 fab952e1 2020-10-03 op If a user request path is a directory,
 59 fab952e1 2020-10-03 op .Nm
 60 fab952e1 2020-10-03 op will try to serve a
 61 fab952e1 2020-10-03 op .Pa index.gmi
 62 fab952e1 2020-10-03 op file inside that directory.
 63 fab952e1 2020-10-03 op .Pp
 64 3e4749f7 2020-10-02 op The options are as follows:
 65 3e4749f7 2020-10-02 op .Bl -tag -width 12m
 66 3e4749f7 2020-10-02 op .It Fl c Ar cert.pem
 67 3e4749f7 2020-10-02 op The certificate to use, by default is
 68 fab952e1 2020-10-03 op .Pa cert.pem .
 69 3e4749f7 2020-10-02 op .It Fl d Ar docs
 70 3e4749f7 2020-10-02 op The root directory to serve.
 71 3e4749f7 2020-10-02 op .Nm
 72 a5d310bc 2020-11-10 op won't serve any file that is outside that directory.
 73 a5d310bc 2020-11-10 op By default is
 74 0ed56567 2020-11-06 op .Pa docs .
 75 d7802bb4 2020-12-02 op .It Fl f
 76 d7802bb4 2020-12-02 op stays and log in the foreground, do not daemonize the process.
 77 3e4749f7 2020-10-02 op .It Fl h
 78 fab952e1 2020-10-03 op Print the usage and exit.
 79 3e4749f7 2020-10-02 op .It Fl k Ar key.pem
 80 3e4749f7 2020-10-02 op The key for the certificate, by default is
 81 fab952e1 2020-10-03 op .Pa key.pem .
 82 721e2325 2020-11-18 op .It Fl p Ar port
 83 721e2325 2020-11-18 op The port to bind to, by default 1965.
 84 0ed56567 2020-11-06 op .It Fl x Ar dir
 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.
 87 3e4749f7 2020-10-02 op .El
 88 72342dc9 2020-11-06 op .Sh CGI
 89 0ed56567 2020-11-06 op When CGI scripts are enabled for a directory, a request for an
 90 0ed56567 2020-11-06 op executable file will execute it and fed its output to the client.
 91 72342dc9 2020-11-06 op .Pp
 92 0ed56567 2020-11-06 op The CGI scripts will inherit the environment from
 93 0ed56567 2020-11-06 op .Nm
 94 0ed56567 2020-11-06 op with these additional variables set:
 95 a5d310bc 2020-11-10 op .Bl -tag -width 18m
 96 0ed56567 2020-11-06 op .It Ev SERVER_SOFTWARE
 97 0ed56567 2020-11-06 op "gmid"
 98 0ed56567 2020-11-06 op .It Ev SERVER_PORT
 99 0ed56567 2020-11-06 op "1965"
100 a5d310bc 2020-11-10 op .It Ev SCRIPT_NAME
101 a5d310bc 2020-11-10 op The (public) path to the script.
102 a5d310bc 2020-11-10 op .It Ev SCRIPT_EXECUTABLE
103 a5d310bc 2020-11-10 op The full path to the executable.
104 a5d310bc 2020-11-10 op .It Ev REQUEST_URI
105 a5d310bc 2020-11-10 op The user request (without the query parameters.)
106 a5d310bc 2020-11-10 op .It Ev REQUEST_RELATIVE
107 a5d310bc 2020-11-10 op The request relative to the script.
108 0ed56567 2020-11-06 op .It Ev QUERY_STRING
109 a5d310bc 2020-11-10 op The query parameters.
110 a5d310bc 2020-11-10 op .It Ev REMOTE_HOST
111 a5d310bc 2020-11-10 op The remote IP address.
112 677afbd3 2020-12-02 op .It Ev REMOTE_ADDR
113 677afbd3 2020-12-02 op The remote IP address.
114 a5d310bc 2020-11-10 op .It Ev DOCUMENT_ROOT
115 a5d310bc 2020-11-10 op The root directory being served, the one provided with the
116 a5d310bc 2020-11-10 op .Ar d
117 a5d310bc 2020-11-10 op parameter to
118 a5d310bc 2020-11-10 op .Nm
119 677afbd3 2020-12-02 op .It Ev AUTH_TYPE
120 677afbd3 2020-12-02 op The string "Certificate" if the client used a certificate, otherwise unset.
121 677afbd3 2020-12-02 op .It Ev REMOTE_USER
122 677afbd3 2020-12-02 op The subject of the client certificate if provided, otherwise unset.
123 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_ISSUER
124 677afbd3 2020-12-02 op The is the issuer of the client certificate if provided, otherwise unset.
125 677afbd3 2020-12-02 op .It Ev TLS_CLIENT_HASH
126 677afbd3 2020-12-02 op The hash of the client certificate if provided, otherwise unset.
127 677afbd3 2020-12-02 op The format is "ALGO:HASH".
128 0ed56567 2020-11-06 op .El
129 a5d310bc 2020-11-10 op .Pp
130 a5d310bc 2020-11-10 op Let's say you have a script in
131 a5d310bc 2020-11-10 op .Pa /cgi-bin/script
132 a5d310bc 2020-11-10 op and the user request is
133 a5d310bc 2020-11-10 op .Pa /cgi-bin/script/foo/bar?quux .
134 a5d310bc 2020-11-10 op Then
135 a5d310bc 2020-11-10 op .Ev SCRIPT_NAME
136 a5d310bc 2020-11-10 op will be
137 a5d310bc 2020-11-10 op .Pa /cgi-bin/script ,
138 a5d310bc 2020-11-10 op .Ev SCRIPT_EXECUTABLE
139 a5d310bc 2020-11-10 op will be
140 a5d310bc 2020-11-10 op .Pa $DOCUMENT_ROOT/cgi-bin/script ,
141 a5d310bc 2020-11-10 op .Ev REQUEST_URI
142 a5d310bc 2020-11-10 op will be
143 a5d310bc 2020-11-10 op .Pa /cgi-bin/script/foo/bar ,
144 a5d310bc 2020-11-10 op .Ev REQUEST_RELATIVE
145 a5d310bc 2020-11-10 op will be
146 a5d310bc 2020-11-10 op .Pa foo/bar and
147 a5d310bc 2020-11-10 op .Ev QUERY_STRING
148 a5d310bc 2020-11-10 op will be
149 a5d310bc 2020-11-10 op .Ar quux .
150 3e4749f7 2020-10-02 op .Sh EXAMPLES
151 3e4749f7 2020-10-02 op To quickly getting started
152 6980aad6 2020-10-02 op .Bd -literal -offset indent
153 3e4749f7 2020-10-02 op $ # generate a cert and a key
154 3e4749f7 2020-10-02 op $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
155 3e4749f7 2020-10-02 op         -out cert.pem -days 365 -nodes
156 3e4749f7 2020-10-02 op $ mkdir docs
157 3e4749f7 2020-10-02 op $ cat <<EOF > docs/index.gmi
158 3e4749f7 2020-10-02 op # Hello world
159 3e4749f7 2020-10-02 op test paragraph...
160 3e4749f7 2020-10-02 op EOF
161 3e4749f7 2020-10-02 op $ gmid -c cert.pem -k key.pem -d docs
162 6980aad6 2020-10-02 op .Ed
163 3e4749f7 2020-10-02 op .Pp
164 0ed56567 2020-11-06 op Now you can visit gemini://localhost/ with your preferred gemini
165 0ed56567 2020-11-06 op client.
166 0ed56567 2020-11-06 op .Pp
167 0ed56567 2020-11-06 op To add some CGI scripts, assuming a setup similar to the previous
168 0ed56567 2020-11-06 op example, you can
169 0ed56567 2020-11-06 op .Bd -literal -offset indent
170 0ed56567 2020-11-06 op $ mkdir docs/cgi-bin
171 0ed56567 2020-11-06 op $ cat <<EOF > docs/cgi-bin/hello-world
172 0ed56567 2020-11-06 op #!/bin/sh
173 0ed56567 2020-11-06 op printf "20 text/plain\\r\\n"
174 0ed56567 2020-11-06 op echo "hello world!"
175 0ed56567 2020-11-06 op EOF
176 0ed56567 2020-11-06 op $ gmid -x cgi-bin
177 0ed56567 2020-11-06 op .Ed
178 0ed56567 2020-11-06 op .Pp
179 0ed56567 2020-11-06 op Note that the argument to the
180 0ed56567 2020-11-06 op .Fl x
181 0ed56567 2020-11-06 op option is
182 0ed56567 2020-11-06 op .Pa cgi-bin
183 0ed56567 2020-11-06 op and not
184 0ed56567 2020-11-06 op .Pa docs/cgi-bin ,
185 a5d310bc 2020-11-10 op since it's relative to the document root.
186 3e4749f7 2020-10-02 op .Sh CAVEATS
187 3e4749f7 2020-10-02 op .Bl -bullet
188 3e4749f7 2020-10-02 op .It
189 fab952e1 2020-10-03 op it doesn't support virtual hosts: the host part of the request URL is
190 3e4749f7 2020-10-02 op completely ignored.
191 043acc97 2020-12-25 op .It
192 043acc97 2020-12-25 op a %2F sequence in the path part is indistinguishable from a literal
193 043acc97 2020-12-25 op slash: this is not RFC3986-compliant.
194 3e4749f7 2020-10-02 op .El