mirror of
https://github.com/omar-polo/gmid.git
synced 2024-09-28 21:41:56 +02:00
2c3e53dac6
this fixes a bug introduced with the prefork mechanics: every server process shared the same socket, and this would cause a race condition when multiple server processes asked for a script cgi being executed. This gives each server process its own socket to talk to the executor, so the race cannot happen.
502 lines
12 KiB
Groff
502 lines
12 KiB
Groff
.\" 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 30 2021$
|
|
.Dt GMIND 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gmid
|
|
.Nd simple and secure Gemini server
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl fnv
|
|
.Op Fl c Ar config
|
|
.Ek
|
|
.Nm
|
|
.Bk -words
|
|
.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.
|
|
.Pp
|
|
.Nm
|
|
rereads the configuration file when it receives
|
|
.Dv SIGHUP .
|
|
.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.
|
|
They 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
|
|
will 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
|
|
Verbose mode.
|
|
Multiple
|
|
.Fl v
|
|
options increase the verbosity.
|
|
.It Fl x Pa path
|
|
Enable execution of CGI scripts.
|
|
See the description of the
|
|
.Ic cgi
|
|
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 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 privileges can be dropped.
|
|
Note that
|
|
.Nm
|
|
will enter the chroot after loading the TLS keys, but before opening
|
|
the virtual host root directories.
|
|
It's recommended to keep the TLS keys outside the chroot.
|
|
Future version of
|
|
.Nm
|
|
may require this.
|
|
.It Ic ipv6 Ar bool
|
|
Enable or disable IPv6 support.
|
|
By default is off.
|
|
.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 port Ar portno
|
|
The port to listen on.
|
|
By default is 1965.
|
|
.It Ic prefork Ar number
|
|
Run the specified number of server processes.
|
|
This increases the performance and prevents delays when connecting to
|
|
a server.
|
|
.Nm
|
|
runs 3 server processes by default, when not in config-less mode.
|
|
The maximum number allowed is 16.
|
|
.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 enabled.
|
|
Use
|
|
.Dq tlsv1.3
|
|
to enable only TLSv1.3.
|
|
.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 auto Ic index Ar bool
|
|
If no index file is found, automatically generate a directory listing.
|
|
It's disabled by default.
|
|
.It Ic block Op Ic return Ar code Op Ar meta
|
|
Send a reply and close the connection;
|
|
.Ar code
|
|
is 40
|
|
and
|
|
.Ar meta
|
|
is
|
|
.Dq temporary failure
|
|
by default.
|
|
If
|
|
.Ar code
|
|
is in the 3x range, then
|
|
.Ar meta
|
|
must be provided.
|
|
Inside
|
|
.Ar meta ,
|
|
the following special sequences are replaced:
|
|
.Bl -tag -compact
|
|
.It \&%\&%
|
|
is replaced with a single
|
|
.Sq \&% .
|
|
.It \&%p
|
|
is replaced with the request path.
|
|
.It \&%q
|
|
is replaced with the query string of the request.
|
|
.It \&%P
|
|
is replaced with the server port.
|
|
.It \&%N
|
|
is replaced with the server name.
|
|
.El
|
|
.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 cgi Pa path
|
|
Execute CGI scripts that matches
|
|
.Pa path
|
|
using shell globbing rules.
|
|
.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 entrypoint Pa path
|
|
Make the CGI script at
|
|
.Pa path
|
|
.Pq relative to the Ic root No directory
|
|
handle all the requests for the current virtual host
|
|
.It Ic index Ar string
|
|
Set the directory index file.
|
|
If not specified, it defaults to
|
|
.Pa index.gmi .
|
|
.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 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 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 first
|
|
matching location will be put into effect and the later ones ignored.
|
|
Therefore is advisable to match for more specific paths first and for
|
|
generic ones later on.
|
|
A
|
|
.Ic location
|
|
section may include most of the server configuration rules
|
|
except
|
|
.Ic cert , Ic key , Ic root , Ic location ,
|
|
.Ic entrypoint No and Ic cgi .
|
|
.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 require Ic client Ic ca Pa path
|
|
Allow requests only from clients that provide a certificate signed by
|
|
the CA certificate in
|
|
.Pa path .
|
|
It needs to be a PEM-encoded certificate and it's not relative to the
|
|
chroot.
|
|
.It Ic strip Ar number
|
|
Strip
|
|
.Ar number
|
|
components from the beginning of the path.
|
|
It's only considered for the
|
|
.Ar meta
|
|
parameter in the scope of a
|
|
.Ic block return .
|
|
.El
|
|
.Sh CGI
|
|
When a request for an executable file matches the
|
|
.Ic cgi
|
|
rule, that file will be execute and its output fed to the client.
|
|
.Pp
|
|
The CGI scripts are executed in the directory they reside and inherit
|
|
the environment from
|
|
.Nm
|
|
with these additional variables set:
|
|
.Bl -tag -width 24m
|
|
.It Ev GATEWAY_INTERFACE
|
|
.Dq CGI/1.1
|
|
.It Ev GEMINI_DOCUMENT_ROOT
|
|
The root directory of the virtual host.
|
|
.It Ev GEMINI_SCRIPT_FILENAME
|
|
Full path to the CGI script being executed.
|
|
.It Ev GEMINI_URL
|
|
The full IRI of the request.
|
|
.It Ev GEMINI_URL_PATH
|
|
The path of the request.
|
|
.It Ev PATH_INFO
|
|
The portion of the requested path that is derived from the the IRI
|
|
path hierarchy following the part that identifies the script itself.
|
|
Can be unset.
|
|
.It Ev PATH_TRANSLATED
|
|
Present if and only if
|
|
.Ev PATH_INFO
|
|
is set.
|
|
It represent the translation of the
|
|
.Ev PATH_INFO .
|
|
.Nm
|
|
builds this by appending the
|
|
.Ev PATH_INFO
|
|
to the virtual host directory root.
|
|
.It Ev QUERY_STRING
|
|
The decoded query string.
|
|
.It Ev REMOTE_ADDR , Ev REMOTE_HOST
|
|
Textual representation of the client IP.
|
|
.It Ev REQUEST_METHOD
|
|
This is present only for RFC3875 (CGI) compliance.
|
|
It's always set to the empty string.
|
|
.It Ev SCRIPT_NAME
|
|
The part of the
|
|
.Ev GEMINI_URL_PATH
|
|
that identifies the current CGI script.
|
|
.It Ev SERVER_NAME
|
|
The name of the server
|
|
.It Ev SERVER_PORT
|
|
The port the server is listening on.
|
|
.It Ev SERVER_PROTOCOL
|
|
.Dq GEMINI
|
|
.It Ev SERVER_SOFTWARE
|
|
The name and version of the server, i.e.
|
|
.Dq gmid/1.5
|
|
.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
|
|
.Dq ALGO:HASH .
|
|
.It Ev TLS_CLIENT_NOT_AFTER
|
|
The time corresponding to the end of the validity period of the peer
|
|
certificate in the ISO 8601 format
|
|
.Pq e.g. Dq 2021-02-07T20:17:41Z .
|
|
.It Ev TLS_CLIENT_NOT_BEFORE
|
|
The time corresponding to the start of the validity period of the peer
|
|
certificate in the ISO 8601 format.
|
|
.El
|
|
.Pp
|
|
.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
|
|
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 "/example.com" # in the /var/gemini chroot
|
|
|
|
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 AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
program was written by
|
|
.An Omar Polo Aq Mt op@omarpolo.com .
|
|
.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 is indistinguishable from a literal slash: this is not
|
|
RFC3986-compliant.
|
|
.It
|
|
a %00 sequence is treated as invalid character and thus rejected.
|
|
.El
|