1 207dc0f9 2021-01-02 op .\" Copyright (c) 2021, 2022 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 1595c277 2022-04-07 op .Dd $Mdocdate: April 7 2022$
 15 3f47867e 2021-04-16 op .Dt GMID 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 714685c1 2021-01-30 op .Nd simple and secure 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 38d4db74 2021-02-04 op .Op Fl fnv
 24 15902770 2021-01-15 op .Op Fl c Ar config
 25 8b743dda 2021-06-29 op .Op Fl D Ar macro Ns = Ns Ar value
 26 8e8b2e25 2021-04-28 op .Op Fl P Ar pidfile
 27 38d4db74 2021-02-04 op .Ek
 28 38d4db74 2021-02-04 op .Nm
 29 38d4db74 2021-02-04 op .Bk -words
 30 ba65dcc8 2021-06-29 op .Op Fl 6hVv
 31 14cee926 2022-01-04 op .Op Fl d Ar certs-dir
 32 f28d96d3 2021-01-25 op .Op Fl H Ar hostname
 33 721e2325 2020-11-18 op .Op Fl p Ar port
 34 14cee926 2022-01-04 op .Op Fl x Ar cgi
 35 14cee926 2022-01-04 op .Op Ar dir
 36 3e4749f7 2020-10-02 op .Ek
 37 3e4749f7 2020-10-02 op .Sh DESCRIPTION
 38 3e4749f7 2020-10-02 op .Nm
 39 8ff40039 2021-05-24 op is a simple and minimal gemini server that can serve static files,
 40 8ff40039 2021-05-24 op execute CGI scripts and talk to FastCGI applications.
 41 eb699783 2021-01-18 op It can run without a configuration file with a limited set of features
 42 eb699783 2021-01-18 op available.
 43 3007f565 2021-02-04 op .Pp
 44 3007f565 2021-02-04 op .Nm
 45 3007f565 2021-02-04 op rereads the configuration file when it receives
 46 3007f565 2021-02-04 op .Dv SIGHUP .
 47 3e4749f7 2020-10-02 op .Pp
 48 eb699783 2021-01-18 op The options are as follows:
 49 f28d96d3 2021-01-25 op .Bl -tag -width 14m
 50 14cee926 2022-01-04 op .It Fl c Ar config
 51 f28d96d3 2021-01-25 op Specify the configuration file.
 52 8b743dda 2021-06-29 op .It Fl D Ar macro Ns = Ns Ar value
 53 8b743dda 2021-06-29 op Define
 54 8b743dda 2021-06-29 op .Ar macro
 55 8b743dda 2021-06-29 op to be set to
 56 8b743dda 2021-06-29 op .Ar value
 57 8b743dda 2021-06-29 op on the command line.
 58 8b743dda 2021-06-29 op Overrides the definition of
 59 8b743dda 2021-06-29 op .Ar macro
 60 8b743dda 2021-06-29 op in the config file if present.
 61 46af8c6c 2021-01-27 op .It Fl f
 62 46af8c6c 2021-01-27 op Stays and logs on the foreground.
 63 eb699783 2021-01-18 op .It Fl n
 64 eb699783 2021-01-18 op Check that the configuration is valid, but don't start the server.
 65 f0a01fc7 2021-10-09 op If specified two or more time, dump the configuration in addition to
 66 f0a01fc7 2021-10-09 op verify it.
 67 14cee926 2022-01-04 op .It Fl P Ar pidfile
 68 301e039d 2021-07-29 op Write daemon's pid to the given location.
 69 2b520ad5 2021-07-09 op .Ar pidfile
 70 2b520ad5 2021-07-09 op will also act as lock: if another process is holding a lock on that
 71 2b520ad5 2021-07-09 op file,
 72 8e8b2e25 2021-04-28 op .Nm
 73 2b520ad5 2021-07-09 op will refuse to start.
 74 eb699783 2021-01-18 op .El
 75 3e4749f7 2020-10-02 op .Pp
 76 eb699783 2021-01-18 op If no configuration file is given,
 77 fab952e1 2020-10-03 op .Nm
 78 ebf3373d 2021-12-02 op runs in
 79 ebf3373d 2021-12-02 op .Dq config-less mode
 80 ebf3373d 2021-12-02 op .Pq i.e. runs in the foreground to serve a directory from the shell
 81 ebf3373d 2021-12-02 op and looks for the following options
 82 f28d96d3 2021-01-25 op .Bl -tag -width 14m
 83 85dff1f9 2021-01-11 op .It Fl 6
 84 85dff1f9 2021-01-11 op Enable IPv6.
 85 14cee926 2022-01-04 op .It Fl d Ar certs-path
 86 f28d96d3 2021-01-25 op Directory where certificates for the config-less mode are stored.
 87 301e039d 2021-07-29 op By default it is
 88 f28d96d3 2021-01-25 op .Pa $XDG_DATA_HOME/gmid ,
 89 f28d96d3 2021-01-25 op i.e.
 90 f28d96d3 2021-01-25 op .Pa ~/.local/share/gmid .
 91 71cf3975 2021-01-25 op .It Fl H Ar hostname
 92 2b520ad5 2021-07-09 op The hostname
 93 301e039d 2021-07-29 op .Po
 94 2b520ad5 2021-07-09 op .Ar localhost
 95 301e039d 2021-07-29 op by default
 96 301e039d 2021-07-29 op .Pc .
 97 f28d96d3 2021-01-25 op Certificates for the given
 98 f28d96d3 2021-01-25 op .Ar hostname
 99 f28d96d3 2021-01-25 op are searched inside the
100 14cee926 2022-01-04 op .Ar certs-dir
101 f28d96d3 2021-01-25 op directory given with the
102 f28d96d3 2021-01-25 op .Fl d
103 f28d96d3 2021-01-25 op option.
104 714685c1 2021-01-30 op They have the form
105 f28d96d3 2021-01-25 op .Pa hostname.cert.pem
106 f28d96d3 2021-01-25 op and
107 f28d96d3 2021-01-25 op .Pa hostname.key.pem .
108 301e039d 2021-07-29 op If a certificate or a key doesn't exist for a given hostname, they
109 301e039d 2021-07-29 op will be generated automatically.
110 ba65dcc8 2021-06-29 op .It Fl h , Fl -help
111 fab952e1 2020-10-03 op Print the usage and exit.
112 721e2325 2020-11-18 op .It Fl p Ar port
113 eb699783 2021-01-18 op The port to listen on, by default 1965.
114 ba65dcc8 2021-06-29 op .It Fl V , Fl -version
115 ba65dcc8 2021-06-29 op Print the version and exit.
116 8904fa0e 2021-01-27 op .It Fl v
117 3abf91b0 2021-02-07 op Verbose mode.
118 3abf91b0 2021-02-07 op Multiple
119 3abf91b0 2021-02-07 op .Fl v
120 3abf91b0 2021-02-07 op options increase the verbosity.
121 14cee926 2022-01-04 op .It Fl x Ar path
122 301e039d 2021-07-29 op Enable execution of
123 301e039d 2021-07-29 op .Sx CGI
124 301e039d 2021-07-29 op scripts.
125 eb699783 2021-01-18 op See the description of the
126 eb699783 2021-01-18 op .Ic cgi
127 301e039d 2021-07-29 op option in the
128 eb699783 2021-01-18 op .Sq Servers
129 301e039d 2021-07-29 op section below to learn how
130 14cee926 2022-01-04 op .Ar path
131 eb699783 2021-01-18 op is processed.
132 eb699783 2021-01-18 op Cannot be provided more than once.
133 14cee926 2022-01-04 op .It Ar dir
134 f28d96d3 2021-01-25 op The root directory to serve.
135 f28d96d3 2021-01-25 op By default the current working directory is assumed.
136 ee68c361 2021-01-01 op .El
137 e58a447a 2021-07-29 op .Sh LOGGING
138 e58a447a 2021-07-29 op Messages and requests are logged by
139 e58a447a 2021-07-29 op .Xr syslog 3
140 e58a447a 2021-07-29 op using the
141 e58a447a 2021-07-29 op .Dv DAEMON
142 e58a447a 2021-07-29 op facility or printed on
143 e58a447a 2021-07-29 op .Em stderr .
144 e58a447a 2021-07-29 op .Pp
145 e58a447a 2021-07-29 op Requests are logged with the
146 e58a447a 2021-07-29 op .Dv NOTICE
147 e58a447a 2021-07-29 op severity.
148 e58a447a 2021-07-29 op Each request log entry has the following fields, separated by
149 e58a447a 2021-07-29 op whitespace:
150 e58a447a 2021-07-29 op .Pp
151 e58a447a 2021-07-29 op .Bl -bullet -compact
152 e58a447a 2021-07-29 op .It
153 e58a447a 2021-07-29 op Client IP address and the source port number, separated by a colon
154 e58a447a 2021-07-29 op .It
155 e58a447a 2021-07-29 op .Sy GET
156 e58a447a 2021-07-29 op keyword
157 e58a447a 2021-07-29 op .It
158 e58a447a 2021-07-29 op Request URL
159 e58a447a 2021-07-29 op .It
160 e58a447a 2021-07-29 op Response status
161 e58a447a 2021-07-29 op .It
162 e58a447a 2021-07-29 op Response meta
163 e58a447a 2021-07-29 op .El
164 3e4749f7 2020-10-02 op .Sh EXAMPLES
165 f28d96d3 2021-01-25 op Serve the current directory
166 6980aad6 2020-10-02 op .Bd -literal -offset indent
167 f28d96d3 2021-01-25 op $ gmid .
168 6980aad6 2020-10-02 op .Ed
169 3e4749f7 2020-10-02 op .Pp
170 f28d96d3 2021-01-25 op To serve the directory
171 f28d96d3 2021-01-25 op .Pa docs
172 f28d96d3 2021-01-25 op and enable CGI scripts inside
173 2b520ad5 2021-07-09 op .Pa docs/cgi
174 0ed56567 2020-11-06 op .Bd -literal -offset indent
175 f28d96d3 2021-01-25 op $ mkdir docs/cgi
176 b7a99061 2021-04-15 op $ cat <<EOF > docs/cgi/hello
177 0ed56567 2020-11-06 op #!/bin/sh
178 af5f9b27 2021-07-21 op printf "20 text/plain\er\en"
179 f28d96d3 2021-01-25 op echo "hello world"
180 0ed56567 2020-11-06 op EOF
181 f28d96d3 2021-01-25 op $ chmod +x docs/cgi/hello
182 b890467e 2021-03-20 op $ gmid -x '/cgi/*' docs
183 0ed56567 2020-11-06 op .Ed
184 e308526c 2021-07-29 op .Pp
185 e308526c 2021-07-29 op An X.509 certificate must be provided to run
186 e308526c 2021-07-29 op .Nm
187 e308526c 2021-07-29 op using a configuration file.
188 e308526c 2021-07-29 op First, the RSA certificate is created using a wildcard common name:
189 e308526c 2021-07-29 op .Bd -literal -offset indent
190 e308526c 2021-07-29 op # openssl genrsa \-out /etc/ssl/private/example.com.key 4096
191 1298e430 2021-10-09 op # openssl req \-new \-x509 \e
192 1298e430 2021-10-09 op 	\-key /etc/ssl/private/example.com.key \e
193 1298e430 2021-10-09 op 	\-out /etc/ssl/example.com.crt \e
194 1298e430 2021-10-09 op 	\-days 36500 \-nodes \e
195 2bb1776b 2021-07-29 op 	\-subj "/CN=example.com"
196 e308526c 2021-07-29 op # chmod 600 /etc/ssl/example.com.crt
197 e308526c 2021-07-29 op # chmod 600 /etc/ssl/private/example.com.key
198 e308526c 2021-07-29 op .Ed
199 e308526c 2021-07-29 op .Pp
200 e308526c 2021-07-29 op In the example above, a certificate is valid for one hundred years from
201 e308526c 2021-07-29 op the date it was created, which is normal for TOFU.
202 0ed56567 2020-11-06 op .Pp
203 1595c277 2022-04-07 op Then, to run
204 1595c277 2022-04-07 op .Nm
205 1595c277 2022-04-07 op as a daemon:
206 eb699783 2021-01-18 op .Bd -literal -offset indent
207 1595c277 2022-04-07 op $ gmid -c /etc/gmid.conf
208 eb699783 2021-01-18 op .Ed
209 1595c277 2022-04-07 op .Sh SEE ALSO
210 1595c277 2022-04-07 op .Xr gmid.conf 5
211 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
212 ef04b551 2021-01-09 op .Nm
213 eb699783 2021-01-18 op uses the
214 eb699783 2021-01-18 op .Dq Flexible and Economical
215 eb699783 2021-01-18 op UTF-8 decoder written by
216 f28d96d3 2021-01-25 op .An Bjoern Hoehrmann .
217 714685c1 2021-01-30 op .Sh AUTHORS
218 714685c1 2021-01-30 op .An -nosplit
219 714685c1 2021-01-30 op The
220 714685c1 2021-01-30 op .Nm
221 714685c1 2021-01-30 op program was written by
222 714685c1 2021-01-30 op .An Omar Polo Aq Mt op@omarpolo.com .
223 3e4749f7 2020-10-02 op .Sh CAVEATS
224 3e4749f7 2020-10-02 op .Bl -bullet
225 3e4749f7 2020-10-02 op .It
226 2b520ad5 2021-07-09 op All the root directories are opened during the daemon startup; if a
227 2b520ad5 2021-07-09 op root directory is deleted and then re-created,
228 eb699783 2021-01-18 op .Nm
229 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
230 2b520ad5 2021-07-09 op This restriction only applies to the root directories and not their
231 2b520ad5 2021-07-09 op content.
232 043acc97 2020-12-25 op .It
233 714685c1 2021-01-30 op a %2F sequence is indistinguishable from a literal slash: this is not
234 714685c1 2021-01-30 op RFC3986-compliant.
235 00781742 2020-12-25 op .It
236 714685c1 2021-01-30 op a %00 sequence is treated as invalid character and thus rejected.
237 3e4749f7 2020-10-02 op .El