2022-01-02 17:37:07 +01:00
|
|
|
.\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
|
2020-10-02 19:39:00 +02:00
|
|
|
.\"
|
|
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
|
|
.\"
|
|
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
2022-04-07 19:50:37 +02:00
|
|
|
.Dd $Mdocdate: April 7 2022$
|
2021-04-16 15:28:56 +02:00
|
|
|
.Dt GMID 1
|
2020-10-02 19:39:00 +02:00
|
|
|
.Os
|
|
|
|
.Sh NAME
|
|
|
|
.Nm gmid
|
2021-01-30 12:49:27 +01:00
|
|
|
.Nd simple and secure Gemini server
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm
|
|
|
|
.Bk -words
|
2021-02-04 15:38:37 +01:00
|
|
|
.Op Fl fnv
|
2021-01-15 10:17:43 +01:00
|
|
|
.Op Fl c Ar config
|
2021-06-29 16:19:35 +02:00
|
|
|
.Op Fl D Ar macro Ns = Ns Ar value
|
2021-04-28 14:45:22 +02:00
|
|
|
.Op Fl P Ar pidfile
|
2021-02-04 15:38:37 +01:00
|
|
|
.Ek
|
|
|
|
.Nm
|
|
|
|
.Bk -words
|
2021-06-29 13:00:28 +02:00
|
|
|
.Op Fl 6hVv
|
2022-01-05 00:22:14 +01:00
|
|
|
.Op Fl d Ar certs-dir
|
2021-01-25 15:31:34 +01:00
|
|
|
.Op Fl H Ar hostname
|
2020-11-18 09:12:27 +01:00
|
|
|
.Op Fl p Ar port
|
2022-01-05 00:22:14 +01:00
|
|
|
.Op Fl x Ar cgi
|
|
|
|
.Op Ar dir
|
2020-10-02 19:39:00 +02:00
|
|
|
.Ek
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
.Nm
|
2021-05-24 11:07:28 +02:00
|
|
|
is a simple and minimal gemini server that can serve static files,
|
|
|
|
execute CGI scripts and talk to FastCGI applications.
|
2021-01-18 22:52:01 +01:00
|
|
|
It can run without a configuration file with a limited set of features
|
|
|
|
available.
|
2020-10-02 19:39:00 +02:00
|
|
|
.Pp
|
2021-02-04 14:34:27 +01:00
|
|
|
.Nm
|
|
|
|
rereads the configuration file when it receives
|
|
|
|
.Dv SIGHUP .
|
|
|
|
.Pp
|
2021-01-18 22:52:01 +01:00
|
|
|
The options are as follows:
|
2021-01-25 15:31:34 +01:00
|
|
|
.Bl -tag -width 14m
|
2022-01-05 00:22:14 +01:00
|
|
|
.It Fl c Ar config
|
2021-01-25 15:31:34 +01:00
|
|
|
Specify the configuration file.
|
2021-06-29 16:19:35 +02:00
|
|
|
.It Fl D Ar macro Ns = Ns Ar value
|
|
|
|
Define
|
|
|
|
.Ar macro
|
|
|
|
to be set to
|
|
|
|
.Ar value
|
|
|
|
on the command line.
|
|
|
|
Overrides the definition of
|
|
|
|
.Ar macro
|
|
|
|
in the config file if present.
|
2021-01-27 13:04:37 +01:00
|
|
|
.It Fl f
|
|
|
|
Stays and logs on the foreground.
|
2021-01-18 22:52:01 +01:00
|
|
|
.It Fl n
|
|
|
|
Check that the configuration is valid, but don't start the server.
|
2021-10-09 23:40:55 +02:00
|
|
|
If specified two or more time, dump the configuration in addition to
|
|
|
|
verify it.
|
2022-01-05 00:22:14 +01:00
|
|
|
.It Fl P Ar pidfile
|
2021-07-29 06:13:46 +02:00
|
|
|
Write daemon's pid to the given location.
|
2021-07-09 10:01:22 +02:00
|
|
|
.Ar pidfile
|
|
|
|
will also act as lock: if another process is holding a lock on that
|
|
|
|
file,
|
2021-04-28 14:45:22 +02:00
|
|
|
.Nm
|
2021-07-09 10:01:22 +02:00
|
|
|
will refuse to start.
|
2021-01-18 22:52:01 +01:00
|
|
|
.El
|
2020-10-02 19:39:00 +02:00
|
|
|
.Pp
|
2021-01-18 22:52:01 +01:00
|
|
|
If no configuration file is given,
|
2020-10-03 17:49:09 +02:00
|
|
|
.Nm
|
2021-12-02 09:32:47 +01:00
|
|
|
runs in
|
|
|
|
.Dq config-less mode
|
|
|
|
.Pq i.e. runs in the foreground to serve a directory from the shell
|
|
|
|
and looks for the following options
|
2021-01-25 15:31:34 +01:00
|
|
|
.Bl -tag -width 14m
|
2021-01-11 13:08:50 +01:00
|
|
|
.It Fl 6
|
|
|
|
Enable IPv6.
|
2022-01-05 00:22:14 +01:00
|
|
|
.It Fl d Ar certs-path
|
2021-01-25 15:31:34 +01:00
|
|
|
Directory where certificates for the config-less mode are stored.
|
2021-07-29 06:13:46 +02:00
|
|
|
By default it is
|
2021-01-25 15:31:34 +01:00
|
|
|
.Pa $XDG_DATA_HOME/gmid ,
|
|
|
|
i.e.
|
|
|
|
.Pa ~/.local/share/gmid .
|
2021-01-25 15:32:16 +01:00
|
|
|
.It Fl H Ar hostname
|
2021-07-09 10:01:22 +02:00
|
|
|
The hostname
|
2021-07-29 06:13:46 +02:00
|
|
|
.Po
|
2021-07-09 10:01:22 +02:00
|
|
|
.Ar localhost
|
2021-07-29 06:13:46 +02:00
|
|
|
by default
|
|
|
|
.Pc .
|
2021-01-25 15:31:34 +01:00
|
|
|
Certificates for the given
|
|
|
|
.Ar hostname
|
|
|
|
are searched inside the
|
2022-01-05 00:22:14 +01:00
|
|
|
.Ar certs-dir
|
2021-01-25 15:31:34 +01:00
|
|
|
directory given with the
|
|
|
|
.Fl d
|
|
|
|
option.
|
2021-01-30 12:49:27 +01:00
|
|
|
They have the form
|
2021-01-25 15:31:34 +01:00
|
|
|
.Pa hostname.cert.pem
|
|
|
|
and
|
|
|
|
.Pa hostname.key.pem .
|
2021-07-29 06:13:46 +02:00
|
|
|
If a certificate or a key doesn't exist for a given hostname, they
|
|
|
|
will be generated automatically.
|
2021-06-29 13:00:28 +02:00
|
|
|
.It Fl h , Fl -help
|
2020-10-03 17:49:09 +02:00
|
|
|
Print the usage and exit.
|
2020-11-18 09:12:27 +01:00
|
|
|
.It Fl p Ar port
|
2021-01-18 22:52:01 +01:00
|
|
|
The port to listen on, by default 1965.
|
2021-06-29 13:00:28 +02:00
|
|
|
.It Fl V , Fl -version
|
|
|
|
Print the version and exit.
|
2021-01-28 00:14:16 +01:00
|
|
|
.It Fl v
|
2021-02-07 16:30:28 +01:00
|
|
|
Verbose mode.
|
|
|
|
Multiple
|
|
|
|
.Fl v
|
|
|
|
options increase the verbosity.
|
2022-01-05 00:22:14 +01:00
|
|
|
.It Fl x Ar path
|
2021-07-29 06:13:46 +02:00
|
|
|
Enable execution of
|
|
|
|
.Sx CGI
|
|
|
|
scripts.
|
2021-01-18 22:52:01 +01:00
|
|
|
See the description of the
|
|
|
|
.Ic cgi
|
2021-07-29 06:13:46 +02:00
|
|
|
option in the
|
2021-01-18 22:52:01 +01:00
|
|
|
.Sq Servers
|
2021-07-29 06:13:46 +02:00
|
|
|
section below to learn how
|
2022-01-05 00:22:14 +01:00
|
|
|
.Ar path
|
2021-01-18 22:52:01 +01:00
|
|
|
is processed.
|
|
|
|
Cannot be provided more than once.
|
2022-01-05 00:22:14 +01:00
|
|
|
.It Ar dir
|
2021-01-25 15:31:34 +01:00
|
|
|
The root directory to serve.
|
|
|
|
By default the current working directory is assumed.
|
2021-01-18 22:52:01 +01:00
|
|
|
.El
|
2021-07-29 06:13:43 +02:00
|
|
|
.Sh LOGGING
|
|
|
|
Messages and requests are logged by
|
|
|
|
.Xr syslog 3
|
|
|
|
using the
|
|
|
|
.Dv DAEMON
|
|
|
|
facility or printed on
|
|
|
|
.Em stderr .
|
|
|
|
.Pp
|
|
|
|
Requests are logged with the
|
|
|
|
.Dv NOTICE
|
|
|
|
severity.
|
|
|
|
Each request log entry has the following fields, separated by
|
|
|
|
whitespace:
|
|
|
|
.Pp
|
|
|
|
.Bl -bullet -compact
|
|
|
|
.It
|
|
|
|
Client IP address and the source port number, separated by a colon
|
|
|
|
.It
|
|
|
|
.Sy GET
|
|
|
|
keyword
|
|
|
|
.It
|
|
|
|
Request URL
|
|
|
|
.It
|
|
|
|
Response status
|
|
|
|
.It
|
|
|
|
Response meta
|
|
|
|
.El
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh EXAMPLES
|
2021-01-25 15:31:34 +01:00
|
|
|
Serve the current directory
|
2020-10-02 19:44:32 +02:00
|
|
|
.Bd -literal -offset indent
|
2021-01-25 15:31:34 +01:00
|
|
|
$ gmid .
|
2020-10-02 19:44:32 +02:00
|
|
|
.Ed
|
2020-10-02 19:39:00 +02:00
|
|
|
.Pp
|
2021-01-25 15:31:34 +01:00
|
|
|
To serve the directory
|
|
|
|
.Pa docs
|
|
|
|
and enable CGI scripts inside
|
2021-07-09 10:01:22 +02:00
|
|
|
.Pa docs/cgi
|
2020-11-06 18:11:45 +01:00
|
|
|
.Bd -literal -offset indent
|
2021-01-25 15:31:34 +01:00
|
|
|
$ mkdir docs/cgi
|
2021-04-15 22:14:18 +02:00
|
|
|
$ cat <<EOF > docs/cgi/hello
|
2020-11-06 18:11:45 +01:00
|
|
|
#!/bin/sh
|
2021-07-21 09:56:41 +02:00
|
|
|
printf "20 text/plain\er\en"
|
2021-01-25 15:31:34 +01:00
|
|
|
echo "hello world"
|
2020-11-06 18:11:45 +01:00
|
|
|
EOF
|
2021-01-25 15:31:34 +01:00
|
|
|
$ chmod +x docs/cgi/hello
|
2021-03-20 12:46:12 +01:00
|
|
|
$ gmid -x '/cgi/*' docs
|
2020-11-06 18:11:45 +01:00
|
|
|
.Ed
|
|
|
|
.Pp
|
2022-04-08 16:08:33 +02:00
|
|
|
To run
|
2021-07-29 06:13:45 +02:00
|
|
|
.Nm
|
2022-04-08 16:08:33 +02:00
|
|
|
as a deamon a configuration file and a X.509 certificate must be provided.
|
|
|
|
A self-signed certificate, which are commonly used in the Geminispace,
|
|
|
|
can be generated using for e.g.\&
|
|
|
|
.Xr openssl 1 :
|
2021-07-29 06:13:45 +02:00
|
|
|
.Bd -literal -offset indent
|
2022-04-08 16:08:33 +02:00
|
|
|
# openssl req \-x509 \-newkey rsa:4096 \-nodes \e
|
|
|
|
\-keyout /etc/ssl/private/example.com.key \e
|
|
|
|
\-out /etc/ssl/example.com.pem \e
|
|
|
|
\-days 365 \-subj "/CN=example.com"
|
2021-07-29 06:13:45 +02:00
|
|
|
# chmod 600 /etc/ssl/example.com.crt
|
|
|
|
# chmod 600 /etc/ssl/private/example.com.key
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2022-04-08 16:08:33 +02:00
|
|
|
Then
|
2022-04-07 19:50:37 +02:00
|
|
|
.Nm
|
2022-04-08 16:08:33 +02:00
|
|
|
can be started with
|
2021-01-25 15:31:34 +01:00
|
|
|
.Bd -literal -offset indent
|
2022-04-08 16:08:33 +02:00
|
|
|
# gmid -c /etc/gmid.conf
|
2021-01-25 15:31:34 +01:00
|
|
|
.Ed
|
2022-04-07 19:50:37 +02:00
|
|
|
.Sh SEE ALSO
|
|
|
|
.Xr gmid.conf 5
|
2021-01-09 21:32:23 +01:00
|
|
|
.Sh ACKNOWLEDGEMENTS
|
|
|
|
.Nm
|
2021-01-18 22:52:01 +01:00
|
|
|
uses the
|
|
|
|
.Dq Flexible and Economical
|
|
|
|
UTF-8 decoder written by
|
2021-01-25 15:31:34 +01:00
|
|
|
.An Bjoern Hoehrmann .
|
2021-01-30 12:49:27 +01:00
|
|
|
.Sh AUTHORS
|
|
|
|
.An -nosplit
|
|
|
|
The
|
|
|
|
.Nm
|
|
|
|
program was written by
|
|
|
|
.An Omar Polo Aq Mt op@omarpolo.com .
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh CAVEATS
|
|
|
|
.Bl -bullet
|
|
|
|
.It
|
2021-07-09 10:01:22 +02:00
|
|
|
All the root directories are opened during the daemon startup; if a
|
|
|
|
root directory is deleted and then re-created,
|
2021-01-18 22:52:01 +01:00
|
|
|
.Nm
|
|
|
|
won't be able to serve files inside that directory until a restart.
|
2021-07-09 10:01:22 +02:00
|
|
|
This restriction only applies to the root directories and not their
|
|
|
|
content.
|
2020-12-25 13:15:15 +01:00
|
|
|
.It
|
2021-01-30 12:49:27 +01:00
|
|
|
a %2F sequence is indistinguishable from a literal slash: this is not
|
|
|
|
RFC3986-compliant.
|
2020-12-26 00:37:43 +01:00
|
|
|
.It
|
2021-01-30 12:49:27 +01:00
|
|
|
a %00 sequence is treated as invalid character and thus rejected.
|
2020-10-02 19:39:00 +02:00
|
|
|
.El
|