1 207dc0f9 2021-01-02 op .\" Copyright (c) 2021, 2022 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 1595c277 2022-04-07 op .Dd $Mdocdate: April 7 2022$
19 714685c1 2021-01-30 op .Nd simple and secure Gemini server
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
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
37 3e4749f7 2020-10-02 op .Sh DESCRIPTION
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
45 3007f565 2021-02-04 op rereads the configuration file when it receives
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
57 8b743dda 2021-06-29 op on the command line.
58 8b743dda 2021-06-29 op Overrides the definition of
60 8b743dda 2021-06-29 op in the config file if present.
62 46af8c6c 2021-01-27 op Stays and logs on the foreground.
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
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.
70 2b520ad5 2021-07-09 op will also act as lock: if another process is holding a lock on that
73 2b520ad5 2021-07-09 op will refuse to start.
76 eb699783 2021-01-18 op If no configuration file is given,
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
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 ,
90 f28d96d3 2021-01-25 op .Pa ~/.local/share/gmid .
91 71cf3975 2021-01-25 op .It Fl H Ar hostname
97 f28d96d3 2021-01-25 op Certificates for the given
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
104 714685c1 2021-01-30 op They have the form
105 f28d96d3 2021-01-25 op .Pa hostname.cert.pem
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.
117 3abf91b0 2021-02-07 op Verbose mode.
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
125 eb699783 2021-01-18 op See the description of the
127 301e039d 2021-07-29 op option in the
129 301e039d 2021-07-29 op section below to learn how
131 eb699783 2021-01-18 op is processed.
132 eb699783 2021-01-18 op Cannot be provided more than once.
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.
138 e58a447a 2021-07-29 op Messages and requests are logged by
142 e58a447a 2021-07-29 op facility or printed on
145 e58a447a 2021-07-29 op Requests are logged with the
148 e58a447a 2021-07-29 op Each request log entry has the following fields, separated by
151 e58a447a 2021-07-29 op .Bl -bullet -compact
153 e58a447a 2021-07-29 op Client IP address and the source port number, separated by a colon
160 e58a447a 2021-07-29 op Response status
162 e58a447a 2021-07-29 op Response meta
165 f28d96d3 2021-01-25 op Serve the current directory
166 6980aad6 2020-10-02 op .Bd -literal -offset indent
170 f28d96d3 2021-01-25 op To serve the directory
172 f28d96d3 2021-01-25 op and enable CGI scripts inside
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
178 af5f9b27 2021-07-21 op printf "20 text/plain\er\en"
179 f28d96d3 2021-01-25 op echo "hello world"
181 f28d96d3 2021-01-25 op $ chmod +x docs/cgi/hello
182 b890467e 2021-03-20 op $ gmid -x '/cgi/*' docs
187 5eb842cd 2022-04-08 op as a deamon a configuration file and a X.509 certificate must be provided.
188 5eb842cd 2022-04-08 op A self-signed certificate, which are commonly used in the Geminispace,
189 5eb842cd 2022-04-08 op can be generated using for e.g.\&
190 5eb842cd 2022-04-08 op .Xr openssl 1 :
191 e308526c 2021-07-29 op .Bd -literal -offset indent
192 5eb842cd 2022-04-08 op # openssl req \-x509 \-newkey rsa:4096 \-nodes \e
193 5eb842cd 2022-04-08 op \-keyout /etc/ssl/private/example.com.key \e
194 5eb842cd 2022-04-08 op \-out /etc/ssl/example.com.pem \e
195 5eb842cd 2022-04-08 op \-days 365 \-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
202 5eb842cd 2022-04-08 op can be started with
203 eb699783 2021-01-18 op .Bd -literal -offset indent
204 5eb842cd 2022-04-08 op # gmid -c /etc/gmid.conf
207 1595c277 2022-04-07 op .Xr gmid.conf 5
208 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
211 eb699783 2021-01-18 op .Dq Flexible and Economical
212 eb699783 2021-01-18 op UTF-8 decoder written by
213 f28d96d3 2021-01-25 op .An Bjoern Hoehrmann .
218 714685c1 2021-01-30 op program was written by
219 714685c1 2021-01-30 op .An Omar Polo Aq Mt op@omarpolo.com .
223 2b520ad5 2021-07-09 op All the root directories are opened during the daemon startup; if a
224 2b520ad5 2021-07-09 op root directory is deleted and then re-created,
226 eb699783 2021-01-18 op won't be able to serve files inside that directory until a restart.
227 2b520ad5 2021-07-09 op This restriction only applies to the root directories and not their
230 714685c1 2021-01-30 op a %2F sequence is indistinguishable from a literal slash: this is not
231 714685c1 2021-01-30 op RFC3986-compliant.
233 714685c1 2021-01-30 op a %00 sequence is treated as invalid character and thus rejected.