path: root/gmid.1

.\" Copyright (c) 2021 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: January 25 2021$
.Dt GMIND 1
.Os
.Sh NAME
.Nm gmid
.Nd dead simple zero configuration gemini server
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl fn
.Op Fl c Ar config
|
.Op Fl 6hv
.Op Fl d Pa certs-dir
.Op Fl H Ar hostname
.Op Fl p Ar port
.Op Fl x Pa cgi
.Op Pa dir
.Ek
.Sh DESCRIPTION
.Nm
is a simple and minimal gemini server that can serve static files and
execute CGI scripts.
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 f
and
.Fl n .
.Pp
.Nm
fully supports IRIs (Internationalized Resource Identifiers, see
RFC3987).
.Pp
The options are as follows:
.Bl -tag -width 14m
.It Fl c Pa config
Specify the configuration file.
.It Fl f
Stays and logs on the foreground.
.It Fl n
Check that the configuration is valid, but don't start the server.
.El
.Pp
If no configuration file is given,
.Nm
will look for the following options
.Bl -tag -width 14m
.It Fl 6
Enable IPv6.
.It Fl d Pa certs-path
Directory where certificates for the config-less mode are stored.
By default is
.Pa $XDG_DATA_HOME/gmid ,
i.e.
.Pa ~/.local/share/gmid .
.It Fl H Ar hostname
The hostname, by default
.Ar localhost .
Certificates for the given
.Ar hostname
are searched inside the
.Pa certs-dir
directory given with the
.Fl d
option.
The have the form
.Pa hostname.cert.pem
and
.Pa hostname.key.pem .
If a certificate and key doesn't exists for a given hostname they
would be automatically generated.
.It Fl h
Print the usage and exit.
.It Fl p Ar port
The port to listen on, by default 1965.
.It Fl v
Increase the verbosity of the logs.
.It Fl x Pa path
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 path
is processed.
Cannot be provided more than once.
.It Pa dir
The root directory to serve.
By default the current working directory is assumed.
.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 .
A string is a sequence of characters wrapped in double quotes,
.Dq like this .
.Ss Global Options
.Bl -tag -width 12m
.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 chroot Pa path
.Xr chroot 2
the process to the given
.Pa path .
The daemon has to be run with root privileges and thus the option
.Ic user
needs to be provided, so
.Nm
can drop the privileges.
Note that they are dropped after loading the TLS keys, so it's
recommended to put those outside the chroot.
Future version of
.Nm
may require this.
.It Ic user Ar string
Run the daemon as the given user.
.El
.Ss Servers
Every virtual host is defined by a
.Ic server
block:
.Bl -tag -width Ds
.It Ic server Ar hostname Brq ...
Match the server name using shell globbing rules.
This can be an explicit name,
.Ar www.example.com ,
or a name including a wildcards,
.Ar *.example.com .
.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's relative to the chroot, if enabled.
.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.
.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 .
.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.
.It Ic index Ar string
Set the directory index file.
If not specified, it defaults to
.Pa index.gmi .
.It Ic auto Ic index Ar bool
If no index file is found, automatically generate a directory listing.
It's disabled by default.
.It Ic location Pa path Brq ...
Specify server configuration rules for a specific location.
The
.Pa path
argument will be matched against the request path with shell globbing
rules.
In case of multiple location statements in the same context, the last
matching location will be put into effect.
Therefore is advisable to match for a generic paths first and for more
specific ones later on.
A
.Ic location
section may include most of the server configuration rules
except
.Ic cert , Ic key , Ic root , Ic location No and Ic CGI .
.El
.Sh CGI
When CGI scripts are enabled for a directory, a request for an
executable file will execute it and fed its output to the client.
.Pp
The CGI scripts are executed in the root directory of the virtual
host, or in the served directory if run without config, and inherits
the environment from
.Nm
with these additional variables set:
.Bl -tag -width 18m
.It Ev GATEWAY_INTERFACE
"CGI/1.1"
.It Ev SERVER_PROTOCOL
"GEMINI"
.It Ev SERVER_SOFTWARE
"gmid"
.It Ev SERVER_PORT
"1965"
.It Ev SERVER_NAME
The vhost.
This variable is not available when operating without a configuration.
.It Ev SCRIPT_NAME
The (public) path to the script, e.g.
.Pa "/cgi-bin/example.cgi"
.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.
.It Ev QUERY_STRING
The query parameters.
.It Ev REMOTE_HOST
The remote IP address.
.It Ev REMOTE_ADDR
The remote IP address.
.It Ev DOCUMENT_ROOT
The root directory being served, the one provided with the
.Ar d
parameter to
.Nm
or the root directory of the virtual host.
.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".
.El
.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
.Pa cgi-bin/script ,
.Ev SCRIPT_EXECUTABLE
will be
.Pa $DOCUMENT_ROOT/cgi-bin/script ,
.Ev REQUEST_URI
will be
.Pa cgi-bin/script/foo/bar ,
.Ev REQUEST_RELATIVE
will be
.Pa foo/bar
and
.Ev QUERY_STRING
will be
.Ar quux .
.Sh MIME
To auto-detect the MIME type of the response
.Nm
looks at the file extension and consults its internal table.
By default the following mappings are loaded, but they can be
overridden or extended using the
.Ic mime
configuration option.
If no MIME is found, the value of
.Ic default type
matching the file
.Ic location
will be used, which is
.Dq application/octet-stream
by default.
.Pp
.Bl -tag -offset indent -width 14m -compact
.It gemini, gmi
text/gemini
.It gif
image/gif
.It jpeg
image/jpeg
.It jpg
image/jpeg
.It markdown, md
text/markdown
.It pdf
application/pdf
.It png
image/png
.It svg
image/svg+xml
.It txt
text/plain
.It xml
text/xml
.El
.Sh EXAMPLES
Serve the current directory
.Bd -literal -offset indent
$ gmid .
.Ed
.Pp
To serve the directory
.Pa docs
and enable CGI scripts inside
.Pa docs/cgi ,
you can
.Bd -literal -offset indent
$ mkdir docs/cgi
$ cat <<EOF > cgi/hello
#!/bin/sh
printf "20 text/plain\\r\\n"
echo "hello world"
EOF
$ chmod +x docs/cgi/hello
$ gmid -x cgi docs
.Ed
.Pp
Note that the argument to the
.Fl x
option is
.Pa cgi
and not
.Pa docs/cgi ,
since it's relative to the document root.
.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

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"
	lang "it"
}
.Ed
.Pp
Yet another example, showing how to enable a
.Ic chroot
and use
.Ic location
rule
.Bd -literal -offset indent
chroot "/var/gemini"
user "_gmid"

server "example.com" {
	cert "/path/to/cert.pem"
	key  "/path/to/key.pem"
	root "/var/gemini/example.com"

	location "/static/" {
		auto index on
		index "index.gemini"
	}
}
.Ed
.Sh ACKNOWLEDGEMENTS
.Nm
uses the
.Dq Flexible and Economical
UTF-8 decoder written by
.An Bjoern Hoehrmann .
.Sh CAVEATS
.Bl -bullet
.It
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.
.It
a %2F sequence in the path part is indistinguishable from a literal
slash: this is not RFC3986-compliant.
.It
a %00 sequence either in the path or in the query part is treated as
invalid character and thus rejected.
.El