Blame


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 5eb842cd 2022-04-08 op To run
186 e308526c 2021-07-29 op .Nm
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
198 e308526c 2021-07-29 op .Ed
199 e308526c 2021-07-29 op .Pp
200 5eb842cd 2022-04-08 op Then
201 1595c277 2022-04-07 op .Nm
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
205 eb699783 2021-01-18 op .Ed
206 1595c277 2022-04-07 op .Sh SEE ALSO
207 1595c277 2022-04-07 op .Xr gmid.conf 5
208 ef04b551 2021-01-09 op .Sh ACKNOWLEDGEMENTS
209 ef04b551 2021-01-09 op .Nm
210 eb699783 2021-01-18 op uses the
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 .
214 714685c1 2021-01-30 op .Sh AUTHORS
215 714685c1 2021-01-30 op .An -nosplit
216 714685c1 2021-01-30 op The
217 714685c1 2021-01-30 op .Nm
218 714685c1 2021-01-30 op program was written by
219 714685c1 2021-01-30 op .An Omar Polo Aq Mt op@omarpolo.com .
220 3e4749f7 2020-10-02 op .Sh CAVEATS
221 3e4749f7 2020-10-02 op .Bl -bullet
222 3e4749f7 2020-10-02 op .It
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,
225 eb699783 2021-01-18 op .Nm
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
228 2b520ad5 2021-07-09 op content.
229 043acc97 2020-12-25 op .It
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.
232 00781742 2020-12-25 op .It
233 714685c1 2021-01-30 op a %00 sequence is treated as invalid character and thus rejected.
234 3e4749f7 2020-10-02 op .El