2020-10-02 19:39:00 +02:00
|
|
|
.\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.Dd $Mdocdate: October 2 2020$
|
|
|
|
.Dt GMIND 1
|
|
|
|
.Os
|
|
|
|
.Sh NAME
|
|
|
|
.Nm gmid
|
2020-10-03 17:49:09 +02:00
|
|
|
.Nd dead simple zero configuration gemini server
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh SYNOPSIS
|
|
|
|
.Nm
|
|
|
|
.Bk -words
|
2021-01-15 10:17:43 +01:00
|
|
|
.Op Fl n
|
|
|
|
.Op Fl c Ar config
|
|
|
|
|
|
2021-01-11 13:08:50 +01:00
|
|
|
.Op Fl 6fh
|
2021-01-15 10:17:43 +01:00
|
|
|
.Op Fl C Ar cert
|
|
|
|
.Op Fl d Ar root
|
|
|
|
.Op Fl K Ar key
|
2020-11-18 09:12:27 +01:00
|
|
|
.Op Fl p Ar port
|
2021-01-18 22:52:01 +01:00
|
|
|
.Op Fl x Ar directory
|
2020-10-02 19:39:00 +02:00
|
|
|
.Ek
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
.Nm
|
2021-01-11 13:51:25 +01:00
|
|
|
is a simple and minimal gemini server that can serve static files and
|
|
|
|
execute CGI scripts.
|
2021-01-18 22:52:01 +01:00
|
|
|
It can run without a configuration file with a limited set of features
|
|
|
|
available.
|
|
|
|
If a configuration file is given, no other flags shall be given,
|
|
|
|
except for
|
|
|
|
.Fl n .
|
2020-10-02 19:39:00 +02:00
|
|
|
.Pp
|
2020-12-26 00:33:11 +01:00
|
|
|
.Nm
|
|
|
|
fully supports IRIs (Internationalized Resource Identifiers, see
|
|
|
|
RFC3987).
|
|
|
|
.Pp
|
2021-01-18 22:52:01 +01:00
|
|
|
The options are as follows:
|
|
|
|
.Bl -tag -width 12m
|
|
|
|
.It Fl c Pa config
|
|
|
|
Specifies the configuration file.
|
|
|
|
.It Fl n
|
|
|
|
Check that the configuration is valid, but don't start the server.
|
|
|
|
.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-01-18 22:52:01 +01:00
|
|
|
will look for the following option
|
2020-10-02 19:39:00 +02:00
|
|
|
.Bl -tag -width 12m
|
2021-01-11 13:08:50 +01:00
|
|
|
.It Fl 6
|
|
|
|
Enable IPv6.
|
2021-01-18 22:52:01 +01:00
|
|
|
.It Fl C Pa file
|
|
|
|
The certificate to use.
|
|
|
|
.It Fl d Pa directory
|
2020-10-02 19:39:00 +02:00
|
|
|
The root directory to serve.
|
2020-12-02 21:18:01 +01:00
|
|
|
.It Fl f
|
2021-01-18 22:52:01 +01:00
|
|
|
Stays and log in the foreground, do not daemonize the process.
|
2020-10-02 19:39:00 +02:00
|
|
|
.It Fl h
|
2020-10-03 17:49:09 +02:00
|
|
|
Print the usage and exit.
|
2021-01-18 22:52:01 +01:00
|
|
|
.It Fl K Pa file
|
|
|
|
The key for the certificate.
|
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.
|
|
|
|
.It Fl x Pa directory
|
|
|
|
Enable execution of CGI scripts.
|
|
|
|
See the description of the
|
|
|
|
.Ic cgi
|
|
|
|
.Ic server
|
|
|
|
option in the section
|
|
|
|
.Sq Servers
|
|
|
|
below to learn how
|
|
|
|
.Pa directory
|
|
|
|
is processed.
|
|
|
|
Cannot be provided more than once.
|
|
|
|
.El
|
|
|
|
.Sh CONFIGURATION FILE
|
|
|
|
The configuration file is divided into two sections:
|
|
|
|
.Bl -tag -width xxxx
|
|
|
|
.It Sy Global Options
|
|
|
|
Global settings for
|
|
|
|
.Nm .
|
|
|
|
.It Sy Servers
|
|
|
|
Virtual hosts definition
|
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
Within the sections, empty lines are ignored and comments can be put
|
|
|
|
anywhere in the file using a hash mark
|
|
|
|
.Pq Sq # ,
|
|
|
|
and extend to the end of the current line.
|
|
|
|
A boolean is either the symbol
|
|
|
|
.Sq on
|
|
|
|
or
|
|
|
|
.Sq off .
|
|
|
|
.Ss Global Options
|
|
|
|
.Bl -tag -width 12m
|
|
|
|
.It Ic daemon Ar bool
|
|
|
|
Enable or disables the daemon mode.
|
|
|
|
In daemon mode
|
|
|
|
.Nm
|
|
|
|
will log to syslog and fork in the background.
|
|
|
|
By default is off.
|
|
|
|
.It Ic ipv6 Ar bool
|
|
|
|
Enable or disable IPv6 support.
|
|
|
|
By default is off.
|
|
|
|
.It Ic port Ar portno
|
|
|
|
The port to listen on.
|
|
|
|
By default is 1965.
|
|
|
|
.It Ic protocols Ar string
|
|
|
|
Specify the TLS protocols to enable.
|
|
|
|
Refer to
|
|
|
|
.Xr tls_config_parse_protocols 3
|
|
|
|
for the valid protocol string values.
|
|
|
|
By default, both TLSv1.3 and TLSv1.2 are used.
|
|
|
|
Use
|
|
|
|
.Dq tlsv1.3
|
|
|
|
to enable only TLSv1.3.
|
|
|
|
.It Ic mime Ar mime-type Ar file-extension
|
|
|
|
Add a mapping for the given
|
|
|
|
.Ar file-extension
|
|
|
|
to the given
|
|
|
|
.Ar mime-type .
|
|
|
|
Both argument are strings.
|
|
|
|
.It Ic default type Ar string
|
|
|
|
Set the default media type that is used if the media type for a
|
|
|
|
specified extension is not found.
|
|
|
|
If not specified, the
|
|
|
|
.Ic default type
|
|
|
|
is set to
|
|
|
|
.Dq application/octet-stream .
|
|
|
|
.El
|
|
|
|
.Ss Servers
|
|
|
|
Every virtual host is defined by a
|
|
|
|
.Ic server
|
|
|
|
block:
|
|
|
|
.Bl -tag -width Ds
|
|
|
|
.It Ic server Ar hostname Brq ...
|
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
Followed by a block of options that is enclosed in curly brackets:
|
|
|
|
.Bl -tag -width Ds
|
|
|
|
.It Ic cert Pa file
|
|
|
|
Path to the certificate to use for this server.
|
|
|
|
The
|
|
|
|
.Pa file
|
|
|
|
should contain a PEM encoded certificate.
|
|
|
|
This option is mandatory.
|
|
|
|
.It Ic key Pa file
|
|
|
|
Specify the private key to use for this server.
|
|
|
|
The
|
|
|
|
.Pa file
|
|
|
|
should contain a PEM encoded private key.
|
|
|
|
This option is mandatory.
|
|
|
|
.It Ic root Pa directory
|
|
|
|
Specify the root directory for this server.
|
|
|
|
This option is mandatory.
|
|
|
|
.It Ic cgi Pa path
|
|
|
|
Enable the execution of CGI scripts if
|
|
|
|
.Pa path
|
|
|
|
is a prefix of the user request string.
|
|
|
|
An empty path "" will effectively enable the execution of any file
|
|
|
|
with the executable bit set inside the root directory.
|
2021-01-19 11:58:29 +01:00
|
|
|
.It Ic lang Ar string
|
|
|
|
Specify the language tag for the text/gemini content served.
|
|
|
|
If not specified, no
|
|
|
|
.Dq lang
|
|
|
|
parameter will be added in the response.
|
2020-10-02 19:39:00 +02:00
|
|
|
.El
|
2020-11-06 13:01:31 +01:00
|
|
|
.Sh CGI
|
2020-11-06 18:11:45 +01:00
|
|
|
When CGI scripts are enabled for a directory, a request for an
|
|
|
|
executable file will execute it and fed its output to the client.
|
2020-11-06 13:01:31 +01:00
|
|
|
.Pp
|
2020-11-06 18:11:45 +01:00
|
|
|
The CGI scripts will inherit the environment from
|
|
|
|
.Nm
|
|
|
|
with these additional variables set:
|
2020-11-10 14:07:36 +01:00
|
|
|
.Bl -tag -width 18m
|
2020-11-06 18:11:45 +01:00
|
|
|
.It Ev SERVER_SOFTWARE
|
|
|
|
"gmid"
|
|
|
|
.It Ev SERVER_PORT
|
|
|
|
"1965"
|
2020-11-10 14:07:36 +01:00
|
|
|
.It Ev SCRIPT_NAME
|
|
|
|
The (public) path to the script.
|
|
|
|
.It Ev SCRIPT_EXECUTABLE
|
|
|
|
The full path to the executable.
|
|
|
|
.It Ev REQUEST_URI
|
|
|
|
The user request (without the query parameters.)
|
|
|
|
.It Ev REQUEST_RELATIVE
|
|
|
|
The request relative to the script.
|
2020-11-06 18:11:45 +01:00
|
|
|
.It Ev QUERY_STRING
|
2020-11-10 14:07:36 +01:00
|
|
|
The query parameters.
|
|
|
|
.It Ev REMOTE_HOST
|
|
|
|
The remote IP address.
|
2020-12-02 15:17:19 +01:00
|
|
|
.It Ev REMOTE_ADDR
|
|
|
|
The remote IP address.
|
2020-11-10 14:07:36 +01:00
|
|
|
.It Ev DOCUMENT_ROOT
|
|
|
|
The root directory being served, the one provided with the
|
|
|
|
.Ar d
|
|
|
|
parameter to
|
|
|
|
.Nm
|
2021-01-18 22:52:01 +01:00
|
|
|
or the root directory of the virtual host.
|
2020-12-02 15:17:19 +01:00
|
|
|
.It Ev AUTH_TYPE
|
|
|
|
The string "Certificate" if the client used a certificate, otherwise unset.
|
|
|
|
.It Ev REMOTE_USER
|
|
|
|
The subject of the client certificate if provided, otherwise unset.
|
|
|
|
.It Ev TLS_CLIENT_ISSUER
|
|
|
|
The is the issuer of the client certificate if provided, otherwise unset.
|
|
|
|
.It Ev TLS_CLIENT_HASH
|
|
|
|
The hash of the client certificate if provided, otherwise unset.
|
|
|
|
The format is "ALGO:HASH".
|
2020-11-06 18:11:45 +01:00
|
|
|
.El
|
2020-11-10 14:07:36 +01:00
|
|
|
.Pp
|
|
|
|
Let's say you have a script in
|
|
|
|
.Pa /cgi-bin/script
|
|
|
|
and the user request is
|
|
|
|
.Pa /cgi-bin/script/foo/bar?quux .
|
|
|
|
Then
|
|
|
|
.Ev SCRIPT_NAME
|
|
|
|
will be
|
2021-01-11 13:51:25 +01:00
|
|
|
.Pa cgi-bin/script ,
|
2020-11-10 14:07:36 +01:00
|
|
|
.Ev SCRIPT_EXECUTABLE
|
|
|
|
will be
|
|
|
|
.Pa $DOCUMENT_ROOT/cgi-bin/script ,
|
|
|
|
.Ev REQUEST_URI
|
|
|
|
will be
|
2021-01-11 13:51:25 +01:00
|
|
|
.Pa cgi-bin/script/foo/bar ,
|
2020-11-10 14:07:36 +01:00
|
|
|
.Ev REQUEST_RELATIVE
|
|
|
|
will be
|
2021-01-11 13:51:25 +01:00
|
|
|
.Pa foo/bar
|
|
|
|
and
|
2020-11-10 14:07:36 +01:00
|
|
|
.Ev QUERY_STRING
|
|
|
|
will be
|
|
|
|
.Ar quux .
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh EXAMPLES
|
|
|
|
To quickly getting started
|
2020-10-02 19:44:32 +02:00
|
|
|
.Bd -literal -offset indent
|
2020-10-02 19:39:00 +02:00
|
|
|
$ # generate a cert and a key
|
|
|
|
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\
|
|
|
|
-out cert.pem -days 365 -nodes
|
|
|
|
$ mkdir docs
|
|
|
|
$ cat <<EOF > docs/index.gmi
|
|
|
|
# Hello world
|
|
|
|
test paragraph...
|
|
|
|
EOF
|
|
|
|
$ gmid -c cert.pem -k key.pem -d docs
|
2020-10-02 19:44:32 +02:00
|
|
|
.Ed
|
2020-10-02 19:39:00 +02:00
|
|
|
.Pp
|
2020-11-06 18:11:45 +01:00
|
|
|
Now you can visit gemini://localhost/ with your preferred gemini
|
|
|
|
client.
|
|
|
|
.Pp
|
|
|
|
To add some CGI scripts, assuming a setup similar to the previous
|
|
|
|
example, you can
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
$ mkdir docs/cgi-bin
|
|
|
|
$ cat <<EOF > docs/cgi-bin/hello-world
|
|
|
|
#!/bin/sh
|
|
|
|
printf "20 text/plain\\r\\n"
|
|
|
|
echo "hello world!"
|
|
|
|
EOF
|
|
|
|
$ gmid -x cgi-bin
|
|
|
|
.Ed
|
|
|
|
.Pp
|
|
|
|
Note that the argument to the
|
|
|
|
.Fl x
|
|
|
|
option is
|
|
|
|
.Pa cgi-bin
|
|
|
|
and not
|
|
|
|
.Pa docs/cgi-bin ,
|
2020-11-10 14:07:36 +01:00
|
|
|
since it's relative to the document root.
|
2021-01-18 22:52:01 +01:00
|
|
|
.Pp
|
|
|
|
The following is an example of a possible configuration for a site
|
|
|
|
that enables only TLSv1.3, adds a mime type for the file extension
|
|
|
|
"rtf" and defines two virtual host:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
ipv6 on # enable ipv6
|
|
|
|
daemon on # enable daemon mode
|
|
|
|
|
|
|
|
protocols "tlsv1.3"
|
|
|
|
|
|
|
|
mime "application/rtf" "rtf"
|
|
|
|
|
|
|
|
server "example.com" {
|
|
|
|
cert "/path/to/cert.pem"
|
|
|
|
key "/path/to/key.pem"
|
|
|
|
root "/var/gemini/example.com"
|
|
|
|
}
|
|
|
|
|
|
|
|
server "it.example.com" {
|
|
|
|
cert "/path/to/cert.pem"
|
|
|
|
key "/path/to/key.pem"
|
|
|
|
root "/var/gemini/it.example.com"
|
|
|
|
cgi "/cgi-bin"
|
|
|
|
}
|
|
|
|
.Ed
|
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
|
|
|
|
.An Bjoern Hoehrmann
|
|
|
|
for its IRI parser.
|
2020-10-02 19:39:00 +02:00
|
|
|
.Sh CAVEATS
|
|
|
|
.Bl -bullet
|
|
|
|
.It
|
2021-01-18 22:52:01 +01:00
|
|
|
The root directories of all virtual hosts are opened during the daemon
|
|
|
|
startup; this means that if a root directory gets deleted and then
|
|
|
|
re-created,
|
|
|
|
.Nm
|
|
|
|
won't be able to serve files inside that directory until a restart.
|
|
|
|
This restriction applies only to the root directories and not their content.
|
2020-12-25 13:15:15 +01:00
|
|
|
.It
|
|
|
|
a %2F sequence in the path part is indistinguishable from a literal
|
|
|
|
slash: this is not RFC3986-compliant.
|
2020-12-26 00:37:43 +01:00
|
|
|
.It
|
|
|
|
a %00 sequence either in the path or in the query part is treated as
|
|
|
|
invalid character and thus rejected.
|
2020-10-02 19:39:00 +02:00
|
|
|
.El
|