2021-01-25 15:31:34 +01:00
|
|
|
.\" Copyright (c) 2021 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.
|
2021-07-29 06:13:43 +02:00
|
|
|
.Dd $Mdocdate: July 29 2021$
|
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
|
2021-01-25 15:31:34 +01:00
|
|
|
.Op Fl d Pa certs-dir
|
|
|
|
.Op Fl H Ar hostname
|
2020-11-18 09:12:27 +01:00
|
|
|
.Op Fl p Ar port
|
2021-01-25 15:31:34 +01:00
|
|
|
.Op Fl x Pa cgi
|
|
|
|
.Op Pa 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
|
2021-01-18 22:52:01 +01:00
|
|
|
.It Fl c Pa 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.
|
2021-04-28 14:45:22 +02:00
|
|
|
.It Fl P Pa 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-01-25 15:31:34 +01:00
|
|
|
will look for the following options
|
|
|
|
.Bl -tag -width 14m
|
2021-01-11 13:08:50 +01:00
|
|
|
.It Fl 6
|
|
|
|
Enable IPv6.
|
2021-01-25 15:31:34 +01:00
|
|
|
.It Fl d Pa certs-path
|
|
|
|
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
|
|
|
|
.Pa certs-dir
|
|
|
|
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.
|
2021-01-25 15:31:34 +01:00
|
|
|
.It Fl x Pa 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
|
2021-01-25 15:31:34 +01:00
|
|
|
.Pa path
|
2021-01-18 22:52:01 +01:00
|
|
|
is processed.
|
|
|
|
Cannot be provided more than once.
|
2021-01-25 15:31:34 +01:00
|
|
|
.It Pa dir
|
|
|
|
The root directory to serve.
|
|
|
|
By default the current working directory is assumed.
|
2021-01-18 22:52:01 +01:00
|
|
|
.El
|
|
|
|
.Sh CONFIGURATION FILE
|
2021-06-29 16:19:35 +02:00
|
|
|
The configuration file is divided into three sections:
|
2021-01-18 22:52:01 +01:00
|
|
|
.Bl -tag -width xxxx
|
2021-06-29 16:19:35 +02:00
|
|
|
.It Sy Macros
|
|
|
|
User-defined variables may be defined and used later, simplifying the
|
|
|
|
configuration file.
|
2021-01-18 22:52:01 +01:00
|
|
|
.It Sy Global Options
|
|
|
|
Global settings for
|
|
|
|
.Nm .
|
|
|
|
.It Sy Servers
|
2021-01-25 15:31:34 +01:00
|
|
|
Virtual hosts definition.
|
2021-01-18 22:52:01 +01:00
|
|
|
.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 .
|
2021-01-25 15:31:34 +01:00
|
|
|
A string is a sequence of characters wrapped in double quotes,
|
|
|
|
.Dq like this .
|
2021-06-29 18:44:17 +02:00
|
|
|
Multiple strings one next to the other are joined into a single
|
|
|
|
string:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
# equivalent to "temporary-failure"
|
|
|
|
block return 40 "temporary" "-" "failure"
|
|
|
|
.Ed
|
2021-06-29 16:19:35 +02:00
|
|
|
.Pp
|
2021-07-09 10:01:22 +02:00
|
|
|
Furthermore, quoting is necessary only when a string needs to contain
|
2021-07-09 14:50:24 +02:00
|
|
|
special characters
|
|
|
|
.Pq like spaces or punctuation ,
|
|
|
|
something that looks like a number or a reserved keyword.
|
2021-07-09 10:01:22 +02:00
|
|
|
The last example could have been written also as:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
block return 40 temporary "-" failure
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2021-06-29 16:19:35 +02:00
|
|
|
Strict ordering of the sections is not enforced, so that is possible
|
|
|
|
to mix macros, options and
|
|
|
|
.Ic server
|
|
|
|
blocks.
|
|
|
|
However, defining all the
|
|
|
|
.Ic server
|
|
|
|
blocks after the macros and the global options is recommended.
|
2021-07-09 14:50:24 +02:00
|
|
|
.Pp
|
|
|
|
Newlines are often optional, except around top-level instructions, and
|
|
|
|
semicolons
|
|
|
|
.Dq \&;
|
|
|
|
can also be optionally used to separate options.
|
|
|
|
.Pp
|
|
|
|
Additional configuration files can be included with the
|
|
|
|
.Ic include
|
|
|
|
keyword, for example:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
include "/etc/gmid.conf.local"
|
|
|
|
.Ed
|
2021-06-29 16:19:35 +02:00
|
|
|
.Ss Macros
|
|
|
|
Macros can be defined that will later be expanded in context.
|
|
|
|
Macro names must start with a letter, digit or underscore and may
|
|
|
|
contain any of those characters.
|
2021-07-02 11:05:22 +02:00
|
|
|
Macros names may not be reserved words.
|
2021-06-29 18:35:06 +02:00
|
|
|
Macros are not expanded inside quotes.
|
2021-06-29 16:19:35 +02:00
|
|
|
.Pp
|
2021-07-09 14:50:24 +02:00
|
|
|
Two kinds of macros are supported: variable-like and proper macros.
|
|
|
|
When a macro is invoked with a
|
|
|
|
.Dq $
|
|
|
|
before its name its expanded as a string, whereas when it's invoked
|
|
|
|
with a
|
|
|
|
.Dq @
|
|
|
|
its expanded in-place.
|
|
|
|
.Pp
|
2021-06-29 16:19:35 +02:00
|
|
|
For example:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
dir = "/var/gemini"
|
2021-07-10 23:43:22 +02:00
|
|
|
certdir = "/etc/keys"
|
2021-07-09 14:50:24 +02:00
|
|
|
common = "lang it; auto index on"
|
2021-06-29 16:19:35 +02:00
|
|
|
|
|
|
|
server "foo" {
|
2021-07-11 09:47:19 +02:00
|
|
|
root $dir "/foo" # -> /var/gemini/foo
|
2021-07-10 23:43:22 +02:00
|
|
|
cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
|
|
|
|
key $certdir "/foo.pem" # -> /etc/keys/foo.pem
|
2021-07-09 14:50:24 +02:00
|
|
|
@common
|
2021-06-29 16:19:35 +02:00
|
|
|
}
|
|
|
|
.Ed
|
2021-01-18 22:52:01 +01:00
|
|
|
.Ss Global Options
|
|
|
|
.Bl -tag -width 12m
|
2021-01-25 11:30:07 +01:00
|
|
|
.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
|
2021-01-30 12:49:27 +01:00
|
|
|
needs to be provided, so privileges can be dropped.
|
|
|
|
Note that
|
2021-01-25 11:30:07 +01:00
|
|
|
.Nm
|
2021-01-30 12:49:27 +01:00
|
|
|
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.
|
2021-01-25 11:30:07 +01:00
|
|
|
Future version of
|
|
|
|
.Nm
|
2021-04-15 21:43:46 +02:00
|
|
|
may enforce this.
|
2021-02-06 19:50:42 +01:00
|
|
|
.It Ic ipv6 Ar bool
|
2021-07-09 10:01:22 +02:00
|
|
|
Enable or disable IPv6 support, off by default.
|
2021-07-08 22:29:05 +02:00
|
|
|
.It Ic map Ar mime-type Cm to-ext Ar file-extension
|
2021-07-09 10:01:22 +02:00
|
|
|
Map
|
|
|
|
.Ar mime-type
|
2021-02-06 19:50:42 +01:00
|
|
|
to the given
|
2021-07-09 10:01:22 +02:00
|
|
|
.Ar file-extension .
|
2021-02-06 19:50:42 +01:00
|
|
|
Both argument are strings.
|
|
|
|
.It Ic port Ar portno
|
|
|
|
The port to listen on.
|
2021-07-09 10:01:22 +02:00
|
|
|
1965 by default.
|
2021-02-07 13:05:32 +01:00
|
|
|
.It Ic prefork Ar number
|
|
|
|
Run the specified number of server processes.
|
|
|
|
This increases the performance and prevents delays when connecting to
|
|
|
|
a server.
|
2021-07-09 10:01:22 +02:00
|
|
|
When not in config-less mode,
|
2021-02-07 13:05:32 +01:00
|
|
|
.Nm
|
2021-07-09 10:01:22 +02:00
|
|
|
runs 3 server processes by default.
|
2021-03-03 18:22:01 +01:00
|
|
|
The maximum number allowed is 16.
|
2021-02-06 19:50:42 +01:00
|
|
|
.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.
|
2021-01-25 11:30:07 +01:00
|
|
|
.It Ic user Ar string
|
|
|
|
Run the daemon as the given user.
|
2021-01-18 22:52:01 +01:00
|
|
|
.El
|
|
|
|
.Ss Servers
|
|
|
|
Every virtual host is defined by a
|
|
|
|
.Ic server
|
|
|
|
block:
|
|
|
|
.Bl -tag -width Ds
|
|
|
|
.It Ic server Ar hostname Brq ...
|
2021-01-28 17:29:06 +01:00
|
|
|
Match the server name using shell globbing rules.
|
2021-07-09 10:01:22 +02:00
|
|
|
It can be an explicit name,
|
2021-01-21 10:17:13 +01:00
|
|
|
.Ar www.example.com ,
|
|
|
|
or a name including a wildcards,
|
|
|
|
.Ar *.example.com .
|
2021-01-18 22:52:01 +01:00
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
Followed by a block of options that is enclosed in curly brackets:
|
|
|
|
.Bl -tag -width Ds
|
2021-04-29 20:23:35 +02:00
|
|
|
.It Ic alias Ar name
|
|
|
|
Specify an additional alias
|
|
|
|
.Ar name
|
|
|
|
for this server.
|
2021-02-06 19:50:42 +01:00
|
|
|
.It Ic auto Ic index Ar bool
|
|
|
|
If no index file is found, automatically generate a directory listing.
|
2021-07-09 10:01:22 +02:00
|
|
|
Disabled by default.
|
2021-02-06 19:50:42 +01:00
|
|
|
.It Ic block Op Ic return Ar code Op Ar meta
|
|
|
|
Send a reply and close the connection;
|
2021-07-09 10:01:22 +02:00
|
|
|
by default
|
2021-02-06 19:50:42 +01:00
|
|
|
.Ar code
|
|
|
|
is 40
|
|
|
|
and
|
|
|
|
.Ar meta
|
|
|
|
is
|
2021-07-09 10:01:22 +02:00
|
|
|
.Dq temporary failure .
|
2021-02-06 19:50:42 +01:00
|
|
|
If
|
|
|
|
.Ar code
|
|
|
|
is in the 3x range, then
|
|
|
|
.Ar meta
|
2021-07-09 10:01:22 +02:00
|
|
|
is mandatory.
|
2021-02-06 19:50:42 +01:00
|
|
|
Inside
|
|
|
|
.Ar meta ,
|
2021-07-09 10:01:22 +02:00
|
|
|
the following special sequences are supported:
|
2021-06-11 18:06:24 +02:00
|
|
|
.Bl -tag -width Ds -compact
|
2021-02-06 19:50:42 +01:00
|
|
|
.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
|
2021-01-18 22:52:01 +01:00
|
|
|
.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
|
2021-07-29 06:13:46 +02:00
|
|
|
Execute
|
|
|
|
.Sx CGI
|
|
|
|
scripts that matches
|
2021-01-18 22:52:01 +01:00
|
|
|
.Pa path
|
2021-02-02 23:38:35 +01:00
|
|
|
using shell globbing rules.
|
2021-01-19 12:28:41 +01:00
|
|
|
.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 .
|
2021-02-06 19:50:42 +01:00
|
|
|
.It Ic entrypoint Pa path
|
2021-04-15 22:13:44 +02:00
|
|
|
Handle all the requests for the current virtual host using the
|
2021-07-29 06:13:46 +02:00
|
|
|
.Sx CGI
|
|
|
|
script at
|
2021-07-09 10:01:22 +02:00
|
|
|
.Pa path ,
|
|
|
|
relative to the current document root.
|
2021-07-09 09:27:15 +02:00
|
|
|
.It Ic env Ar name Cm = Ar value
|
2021-04-28 14:43:17 +02:00
|
|
|
Set the environment variable
|
|
|
|
.Ar name
|
|
|
|
to
|
|
|
|
.Ar value
|
|
|
|
when executing CGI scripts.
|
|
|
|
Can be provided more than once.
|
2021-05-24 11:07:28 +02:00
|
|
|
.\" don't document the "spawn <prog>" form because it probably won't
|
2021-06-11 18:04:22 +02:00
|
|
|
.\" be kept.
|
2021-07-08 22:41:43 +02:00
|
|
|
.It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc
|
2021-07-29 06:13:46 +02:00
|
|
|
Enable
|
|
|
|
.Sx FastCGI
|
|
|
|
instead of serving files.
|
2021-05-24 11:07:28 +02:00
|
|
|
The
|
|
|
|
.Pa socket
|
2021-07-09 10:01:22 +02:00
|
|
|
can either be a UNIX-domain socket or a TCP socket.
|
2021-05-24 11:07:28 +02:00
|
|
|
If the FastCGI application is listening on a UNIX domain socket,
|
|
|
|
.Pa socket
|
|
|
|
is a local path name within the
|
|
|
|
.Xr chroot 2
|
|
|
|
root directory of
|
|
|
|
.Nm .
|
|
|
|
Otherwise, the
|
|
|
|
.Ic tcp
|
|
|
|
keyword must be provided and
|
|
|
|
.Pa socket
|
|
|
|
is interpreted as a hostname or an IP address.
|
|
|
|
.Ar port
|
|
|
|
can be either a port number or the name of a service enclosed in
|
|
|
|
double quotes.
|
2021-07-09 10:01:22 +02:00
|
|
|
If not specified defaults to 9000.
|
2021-02-06 19:50:42 +01:00
|
|
|
.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.
|
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.
|
2021-01-24 15:11:40 +01:00
|
|
|
.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.
|
2021-01-30 13:04:20 +01:00
|
|
|
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.
|
2021-01-24 15:11:40 +01:00
|
|
|
A
|
|
|
|
.Ic location
|
|
|
|
section may include most of the server configuration rules
|
|
|
|
except
|
2021-07-09 10:04:12 +02:00
|
|
|
.Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
|
|
|
|
.Ic location No and Ic param .
|
2021-06-17 11:27:09 +02:00
|
|
|
.It Ic log Ar bool
|
|
|
|
Enable or disable the logging for the current server or location block.
|
2021-07-09 09:27:15 +02:00
|
|
|
.It Ic param Ar name Cm = Ar value
|
2021-06-11 18:04:22 +02:00
|
|
|
Set the param
|
|
|
|
.Ar name
|
|
|
|
to
|
|
|
|
.Ar value
|
|
|
|
for FastCGI.
|
2021-02-06 19:50:42 +01:00
|
|
|
.It Ic root Pa directory
|
2021-07-09 10:01:22 +02:00
|
|
|
Specify the root directory for this server
|
|
|
|
.Pq alas the current Dq document root .
|
|
|
|
It's relative to the chroot if enabled.
|
2021-02-09 23:30:04 +01:00
|
|
|
.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.
|
2021-02-06 18:22:37 +01:00
|
|
|
.It Ic strip Ar number
|
|
|
|
Strip
|
|
|
|
.Ar number
|
2021-05-15 11:51:45 +02:00
|
|
|
components from the beginning of the path before doing a lookup in the
|
|
|
|
root directory.
|
|
|
|
It's also considered for the
|
2021-02-06 18:22:37 +01:00
|
|
|
.Ar meta
|
2021-02-06 19:50:42 +01:00
|
|
|
parameter in the scope of a
|
2021-02-06 18:22:37 +01:00
|
|
|
.Ic block return .
|
2020-10-02 19:39:00 +02:00
|
|
|
.El
|
2020-11-06 13:01:31 +01:00
|
|
|
.Sh CGI
|
2021-02-02 23:38:35 +01:00
|
|
|
When a request for an executable file matches the
|
|
|
|
.Ic cgi
|
2021-07-29 06:13:46 +02:00
|
|
|
rule, that file will be executed and its output fed to the client.
|
2020-11-06 13:01:31 +01:00
|
|
|
.Pp
|
2021-02-01 14:19:06 +01:00
|
|
|
The CGI scripts are executed in the directory they reside and inherit
|
2021-01-24 10:20:38 +01:00
|
|
|
the environment from
|
2020-11-06 18:11:45 +01:00
|
|
|
.Nm
|
|
|
|
with these additional variables set:
|
2021-02-01 14:19:06 +01:00
|
|
|
.Bl -tag -width 24m
|
2021-01-24 11:06:48 +01:00
|
|
|
.It Ev GATEWAY_INTERFACE
|
2021-02-01 14:19:06 +01:00
|
|
|
.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.
|
2021-01-24 11:06:48 +01:00
|
|
|
.It Ev SERVER_PROTOCOL
|
2021-02-01 14:19:06 +01:00
|
|
|
.Dq GEMINI
|
2020-11-06 18:11:45 +01:00
|
|
|
.It Ev SERVER_SOFTWARE
|
2021-02-01 14:19:06 +01:00
|
|
|
The name and version of the server, i.e.
|
2021-09-19 16:48:07 +02:00
|
|
|
.Dq gmid/1.7.3
|
2020-12-02 15:17:19 +01:00
|
|
|
.It Ev AUTH_TYPE
|
2021-01-24 11:06:48 +01:00
|
|
|
The string "Certificate" if the client used a certificate, otherwise
|
|
|
|
unset.
|
2020-12-02 15:17:19 +01:00
|
|
|
.It Ev REMOTE_USER
|
|
|
|
The subject of the client certificate if provided, otherwise unset.
|
|
|
|
.It Ev TLS_CLIENT_ISSUER
|
2021-01-24 11:06:48 +01:00
|
|
|
The is the issuer of the client certificate if provided, otherwise
|
|
|
|
unset.
|
2020-12-02 15:17:19 +01:00
|
|
|
.It Ev TLS_CLIENT_HASH
|
|
|
|
The hash of the client certificate if provided, otherwise unset.
|
2021-02-01 14:19:06 +01:00
|
|
|
The format is
|
|
|
|
.Dq ALGO:HASH .
|
2021-04-13 08:59:54 +02:00
|
|
|
.It Ev TLS_VERSION
|
|
|
|
The TLS version negotiated with the peer.
|
|
|
|
.It Ev TLS_CIPHER
|
|
|
|
The cipher suite negotiated with the peer.
|
|
|
|
.It Ev TLS_CIPHER_STRENGTH
|
|
|
|
The strength in bits for the symmetric cipher that is being used with
|
|
|
|
the peer.
|
2021-02-07 22:47:01 +01:00
|
|
|
.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.
|
2020-11-06 18:11:45 +01:00
|
|
|
.El
|
2021-06-11 18:04:22 +02:00
|
|
|
.Sh FastCGI
|
|
|
|
.Nm
|
|
|
|
optionally supports FastCGI.
|
|
|
|
A
|
|
|
|
.Ic fastcgi
|
|
|
|
rule must be present in a server or location block.
|
|
|
|
Then, all requests matching that server or location will be handled
|
|
|
|
via the specified FastCGI backend.
|
|
|
|
.Pp
|
|
|
|
By default the following variables
|
|
|
|
.Pq parameters
|
|
|
|
are sent, and carry the same semantics as with CGI.
|
|
|
|
More parameters can be added with the
|
|
|
|
.Ic param
|
|
|
|
option.
|
2021-07-09 10:01:22 +02:00
|
|
|
.Pp
|
2021-06-11 18:04:22 +02:00
|
|
|
.Bl -bullet -compact
|
|
|
|
.It
|
|
|
|
GATEWAY_INTERFACE
|
|
|
|
.It
|
|
|
|
GEMINI_URL_PATH
|
|
|
|
.It
|
|
|
|
QUERY_STRING
|
|
|
|
.It
|
|
|
|
REMOTE_ADDR
|
|
|
|
.It
|
|
|
|
REMOTE_HOST
|
|
|
|
.It
|
|
|
|
REQUEST_METHOD
|
|
|
|
.It
|
|
|
|
SERVER_NAME
|
|
|
|
.It
|
|
|
|
SERVER_PROTOCOL
|
|
|
|
.It
|
|
|
|
SERVER_SOFTWARE
|
|
|
|
.It
|
|
|
|
AUTH_TYPE
|
|
|
|
.It
|
|
|
|
REMOTE_USER
|
|
|
|
.It
|
|
|
|
TLS_CLIENT_ISSUER
|
|
|
|
.It
|
|
|
|
TLS_CLIENT_HASH
|
|
|
|
.It
|
|
|
|
TLS_VERSION
|
|
|
|
.It
|
|
|
|
TLS_CIPHER
|
|
|
|
.It
|
|
|
|
TLS_CIPHER_STRENGTH
|
|
|
|
.It
|
|
|
|
TLS_CLIENT_NOT_BEFORE
|
|
|
|
.It
|
|
|
|
TLS_CLIENT_NOT_AFTER
|
|
|
|
.El
|
2021-01-28 17:29:06 +01:00
|
|
|
.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
|
2021-07-08 22:29:05 +02:00
|
|
|
.Ic map
|
2021-01-28 17:29:06 +01:00
|
|
|
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
|
2021-04-21 09:51:29 +02:00
|
|
|
.It diff
|
|
|
|
text/x-patch
|
2021-01-28 17:29:06 +01:00
|
|
|
.It gemini, gmi
|
|
|
|
text/gemini
|
|
|
|
.It gif
|
|
|
|
image/gif
|
|
|
|
.It jpeg
|
|
|
|
image/jpeg
|
|
|
|
.It jpg
|
|
|
|
image/jpeg
|
|
|
|
.It markdown, md
|
|
|
|
text/markdown
|
2021-04-21 09:51:29 +02:00
|
|
|
.It patch
|
|
|
|
text/x-patch
|
2021-01-28 17:29:06 +01:00
|
|
|
.It pdf
|
|
|
|
application/pdf
|
|
|
|
.It png
|
|
|
|
image/png
|
|
|
|
.It svg
|
|
|
|
image/svg+xml
|
|
|
|
.It txt
|
|
|
|
text/plain
|
|
|
|
.It xml
|
|
|
|
text/xml
|
|
|
|
.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
|
2021-07-29 06:13:45 +02:00
|
|
|
An X.509 certificate must be provided to run
|
|
|
|
.Nm
|
|
|
|
using a configuration file.
|
|
|
|
First, the RSA certificate is created using a wildcard common name:
|
|
|
|
.Bd -literal -offset indent
|
|
|
|
# openssl genrsa \-out /etc/ssl/private/example.com.key 4096
|
2021-10-09 19:09:56 +02:00
|
|
|
# openssl req \-new \-x509 \e
|
|
|
|
\-key /etc/ssl/private/example.com.key \e
|
|
|
|
\-out /etc/ssl/example.com.crt \e
|
|
|
|
\-days 36500 \-nodes \e
|
2021-07-29 09:48:43 +02:00
|
|
|
\-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
|
|
|
|
In the example above, a certificate is valid for one hundred years from
|
|
|
|
the date it was created, which is normal for TOFU.
|
|
|
|
.Pp
|
2021-01-18 22:52:01 +01:00
|
|
|
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
|
2021-07-29 06:13:45 +02:00
|
|
|
.Qq rtf
|
|
|
|
and defines two virtual host:
|
2021-01-18 22:52:01 +01:00
|
|
|
.Bd -literal -offset indent
|
|
|
|
ipv6 on # enable ipv6
|
|
|
|
|
|
|
|
protocols "tlsv1.3"
|
|
|
|
|
2021-07-08 22:29:05 +02:00
|
|
|
map "application/rtf" to-ext "rtf"
|
2021-01-18 22:52:01 +01:00
|
|
|
|
|
|
|
server "example.com" {
|
2021-07-29 06:13:45 +02:00
|
|
|
cert "/etc/ssl/example.com.crt"
|
|
|
|
key "/etc/ssl/private/example.com.key"
|
2021-01-18 22:52:01 +01:00
|
|
|
root "/var/gemini/example.com"
|
|
|
|
}
|
|
|
|
|
|
|
|
server "it.example.com" {
|
2021-07-29 06:13:45 +02:00
|
|
|
cert "/etc/ssl/example.com.crt"
|
|
|
|
key "/etc/ssl/private/example.com.key"
|
2021-01-18 22:52:01 +01:00
|
|
|
root "/var/gemini/it.example.com"
|
2021-07-09 10:01:22 +02:00
|
|
|
|
|
|
|
# enable cgi scripts inside "cgi-bin"
|
2021-02-02 23:38:35 +01:00
|
|
|
cgi "/cgi-bin/*"
|
2021-07-09 10:01:22 +02:00
|
|
|
|
|
|
|
# set the language for text/gemini files
|
2021-01-21 10:17:13 +01:00
|
|
|
lang "it"
|
2021-01-18 22:52:01 +01:00
|
|
|
}
|
|
|
|
.Ed
|
2021-01-25 15:31:34 +01:00
|
|
|
.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" {
|
2021-07-09 10:01:22 +02:00
|
|
|
cert "/path/to/cert.pem" # absolute path
|
|
|
|
key "/path/to/key.pem" # also absolute
|
|
|
|
root "/example.com" # relative to the chroot
|
2021-01-25 15:31:34 +01:00
|
|
|
|
2021-02-03 15:01:00 +01:00
|
|
|
location "/static/*" {
|
2021-07-09 10:01:22 +02:00
|
|
|
# load the following rules only for
|
|
|
|
# requests that matches "/static/*"
|
|
|
|
|
2021-01-25 15:31:34 +01:00
|
|
|
auto index on
|
|
|
|
index "index.gemini"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
.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
|
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
|