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