mirror of https://github.com/omar-polo/gmid.git
move the documentation of the config file into gmid.conf.5
This commit is contained in:
parent
9bcc265f58
commit
1595c277ef
624
gmid.1
624
gmid.1
|
@ -11,7 +11,7 @@
|
|||
.\" 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: February 26 2022$
|
||||
.Dd $Mdocdate: April 7 2022$
|
||||
.Dt GMID 1
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
@ -134,569 +134,6 @@ Cannot be provided more than once.
|
|||
The root directory to serve.
|
||||
By default the current working directory is assumed.
|
||||
.El
|
||||
.Sh CONFIGURATION FILE
|
||||
The configuration file is divided into three sections:
|
||||
.Bl -tag -width xxxx
|
||||
.It Sy Macros
|
||||
User-defined variables may be defined and used later, simplifying the
|
||||
configuration file.
|
||||
.It Sy Global Options
|
||||
Global settings for
|
||||
.Nm .
|
||||
.It Sy Servers
|
||||
Virtual hosts definition.
|
||||
.It Sy Types
|
||||
Media types and extensions.
|
||||
.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 .
|
||||
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
|
||||
.Pp
|
||||
Furthermore, quoting is necessary only when a string needs to contain
|
||||
special characters
|
||||
.Pq like spaces or punctuation ,
|
||||
something that looks like a number or a reserved keyword.
|
||||
The last example could have been written also as:
|
||||
.Bd -literal -offset indent
|
||||
block return 40 temporary "-" failure
|
||||
.Ed
|
||||
.Pp
|
||||
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.
|
||||
.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
|
||||
.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.
|
||||
Macros names may not be reserved words.
|
||||
Macros are not expanded inside quotes.
|
||||
.Pp
|
||||
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
|
||||
For example:
|
||||
.Bd -literal -offset indent
|
||||
dir = "/var/gemini"
|
||||
certdir = "/etc/keys"
|
||||
common = "lang it; auto index on"
|
||||
|
||||
server "foo" {
|
||||
root $dir "/foo" # -> /var/gemini/foo
|
||||
cert $certdir "/foo.crt" # -> /etc/keys/foo.crt
|
||||
key $certdir "/foo.pem" # -> /etc/keys/foo.pem
|
||||
@common
|
||||
}
|
||||
.Ed
|
||||
.Ss Global Options
|
||||
.Bl -tag -width 12m
|
||||
.It Ic chroot Ar path
|
||||
.Xr chroot 2
|
||||
the process to the given
|
||||
.Ar 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 enforce this.
|
||||
.It Ic ipv6 Ar bool
|
||||
Enable or disable IPv6 support, off by default.
|
||||
.It Ic port Ar portno
|
||||
The port to listen on.
|
||||
1965 by default.
|
||||
.It Ic prefork Ar number
|
||||
Run the specified number of server processes.
|
||||
This increases the performance and prevents delays when connecting to
|
||||
a server.
|
||||
When not in config-less mode,
|
||||
.Nm
|
||||
runs 3 server processes by default.
|
||||
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.
|
||||
It 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 alias Ar name
|
||||
Specify an additional alias
|
||||
.Ar name
|
||||
for this server.
|
||||
.It Ic auto Ic index Ar bool
|
||||
If no index file is found, automatically generate a directory listing.
|
||||
Disabled by default.
|
||||
.It Ic block Op Ic return Ar code Op Ar meta
|
||||
Send a reply and close the connection;
|
||||
by default
|
||||
.Ar code
|
||||
is 40
|
||||
and
|
||||
.Ar meta
|
||||
is
|
||||
.Dq temporary failure .
|
||||
If
|
||||
.Ar code
|
||||
is in the 3x range, then
|
||||
.Ar meta
|
||||
is mandatory.
|
||||
Inside
|
||||
.Ar meta ,
|
||||
the following special sequences are supported:
|
||||
.Bl -tag -width Ds -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 Ar file
|
||||
Path to the certificate to use for this server.
|
||||
.Ar file
|
||||
should contain a PEM encoded certificate.
|
||||
This option is mandatory.
|
||||
.It Ic cgi Ar path
|
||||
Execute
|
||||
.Sx CGI
|
||||
scripts that matches
|
||||
.Ar 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 Ar path
|
||||
Handle all the requests for the current virtual host using the
|
||||
.Sx CGI
|
||||
script at
|
||||
.Ar path ,
|
||||
relative to the current document root.
|
||||
.It Ic env Ar name Cm = Ar value
|
||||
Set the environment variable
|
||||
.Ar name
|
||||
to
|
||||
.Ar value
|
||||
when executing CGI scripts.
|
||||
Can be provided more than once.
|
||||
.\" don't document the "spawn <prog>" form because it probably won't
|
||||
.\" be kept.
|
||||
.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
|
||||
Enable
|
||||
.Sx FastCGI
|
||||
instead of serving files.
|
||||
The
|
||||
.Ar socket
|
||||
can either be a UNIX-domain socket or a TCP socket.
|
||||
If the FastCGI application is listening on a UNIX domain socket,
|
||||
.Ar socket
|
||||
is a local path name within the
|
||||
.Xr chroot 2
|
||||
root directory of
|
||||
.Nm .
|
||||
Otherwise, the
|
||||
.Ic tcp
|
||||
keyword must be provided and
|
||||
.Ar 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.
|
||||
If not specified defaults to 9000.
|
||||
.It Ic index Ar string
|
||||
Set the directory index file.
|
||||
If not specified, it defaults to
|
||||
.Pa index.gmi .
|
||||
.It Ic key Ar file
|
||||
Specify the private key to use for this server.
|
||||
.Ar 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 Ar path Brq ...
|
||||
Specify server configuration rules for a specific location.
|
||||
.Ar 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 alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
|
||||
.Ic location , Ic param No and Ic proxy .
|
||||
.It Ic log Ar bool
|
||||
Enable or disable the logging for the current server or location block.
|
||||
.It Ic param Ar name Cm = Ar value
|
||||
Set the param
|
||||
.Ar name
|
||||
to
|
||||
.Ar value
|
||||
for FastCGI.
|
||||
.It Ic ocsp Ar file
|
||||
Specify an OCSP response to be stapled during TLS handshakes
|
||||
with this server.
|
||||
The
|
||||
.Ar file
|
||||
should contain a DER-format OCSP response retrieved from an
|
||||
OCSP server for the
|
||||
.Ic cert
|
||||
in use.
|
||||
If the OCSP response in
|
||||
.Ar file
|
||||
is empty, OCSP stapling will not be used.
|
||||
The default is to not use OCSP stapling.
|
||||
.It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
|
||||
Set up a reverse proxy.
|
||||
The optional matching rules
|
||||
.Cm proto
|
||||
and
|
||||
.Cm for-host
|
||||
can be used to enable proxying only for protocols matching
|
||||
.Ar name
|
||||
.Po Dq gemini
|
||||
by default
|
||||
.Pc
|
||||
and/or whose request IRI matches
|
||||
.Ar host
|
||||
and
|
||||
.Ar port
|
||||
.Pq 1965 by default .
|
||||
Matching happens using shell globbing rules.
|
||||
.Pp
|
||||
In case of multiple matching proxy blocks in the same context, the
|
||||
first matching proxy will be put into effect and the later ones
|
||||
ignored.
|
||||
.Pp
|
||||
Valid options are:
|
||||
.Bl -tag -width Ds
|
||||
.It Ic cert Ar file
|
||||
Specify the client certificate to use when making requests.
|
||||
.It Ic key Ar file
|
||||
Specify the client certificate key to use when making requests.
|
||||
.It Ic protocols Ar string
|
||||
Specify the TLS protocols allowed when making remote requests.
|
||||
Refer to the
|
||||
.Xr tls_config_parse_protocols 3
|
||||
function for the valid protocol string values.
|
||||
By default, both TLSv1.2 and TLSv1.3 are enabled.
|
||||
.It Ic relay-to Ar host : Ns Op Ar port
|
||||
Relay the request to the given
|
||||
.Ar host
|
||||
at the given
|
||||
.Ar port ,
|
||||
1965 by default.
|
||||
This is the only mandatory option in a
|
||||
.Ic proxy
|
||||
block.
|
||||
.It Ic require Ic client Ic ca Ar file
|
||||
Allow the proxying only from clients that provide a certificate
|
||||
signed by the CA certificate in
|
||||
.Ar file .
|
||||
.It Ic sni Ar hostname
|
||||
Use the given
|
||||
.Ar hostname
|
||||
instead of the one extracted from the
|
||||
.Ic relay-to
|
||||
rule for the TLS handshake with the proxied gemini server.
|
||||
.It Ic use-tls Ar bool
|
||||
Specify whether to use TLS when connecting to the proxied host.
|
||||
Enabled by default.
|
||||
.It Ic verifyname Ar bool
|
||||
Enable or disable the TLS server name verification.
|
||||
Enabled by default.
|
||||
.El
|
||||
.It Ic root Ar directory
|
||||
Specify the root directory for this server
|
||||
.Pq alas the current Dq document root .
|
||||
It's relative to the chroot if enabled.
|
||||
.It Ic require Ic client Ic ca Ar path
|
||||
Allow requests only from clients that provide a certificate signed by
|
||||
the CA certificate in
|
||||
.Ar 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 before doing a lookup in the
|
||||
root directory.
|
||||
It's also considered for the
|
||||
.Ar meta
|
||||
parameter in the scope of a
|
||||
.Ic block return .
|
||||
.El
|
||||
.Ss Types
|
||||
The
|
||||
.Ic types
|
||||
section must include one or more lines of the following syntax, enclosed
|
||||
in curly brances:
|
||||
.Bl -tag -width Ds
|
||||
.It Ar type/subtype Ar name Op Ar name ...
|
||||
Set the media
|
||||
.Ar type
|
||||
and
|
||||
.Ar subtype
|
||||
to the specified extension
|
||||
.Ar name .
|
||||
One or more names can be specified per line.
|
||||
Earch line may end with an optional semicolon.
|
||||
.It Ic include Ar file
|
||||
Include types definition from an external file, for example
|
||||
.Pa /usr/share/misc/mime.types .
|
||||
.El
|
||||
.Sh CGI
|
||||
When a request for an executable file matches the
|
||||
.Ic cgi
|
||||
rule, that file will be executed 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.8.3
|
||||
.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_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.
|
||||
.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
|
||||
.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.
|
||||
.Pp
|
||||
.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
|
||||
.Sh MEDIA TYPES
|
||||
To auto-detect the MIME type of the response
|
||||
.Nm
|
||||
looks at the file extension and consults an internal table.
|
||||
If no MIME is found, the value of
|
||||
.Ic default type
|
||||
matching the file
|
||||
.Ic location
|
||||
will be used, or
|
||||
.Dq application/octet-stream .
|
||||
.Pp
|
||||
By default the following mappings are loaded, but they can be
|
||||
overridden or extended using the
|
||||
.Ic type Brq ...
|
||||
block.
|
||||
.Pp
|
||||
.Bl -tag -offset indent -width 14m -compact
|
||||
.It diff
|
||||
text/x-patch
|
||||
.It gemini, gmi
|
||||
text/gemini
|
||||
.It gif
|
||||
image/gif
|
||||
.It jpeg
|
||||
image/jpeg
|
||||
.It jpg
|
||||
image/jpeg
|
||||
.It markdown, md
|
||||
text/markdown
|
||||
.It patch
|
||||
text/x-patch
|
||||
.It pdf
|
||||
application/pdf
|
||||
.It png
|
||||
image/png
|
||||
.It svg
|
||||
image/svg+xml
|
||||
.It txt
|
||||
text/plain
|
||||
.It xml
|
||||
text/xml
|
||||
.El
|
||||
.Sh LOGGING
|
||||
Messages and requests are logged by
|
||||
.Xr syslog 3
|
||||
|
@ -763,61 +200,14 @@ First, the RSA certificate is created using a wildcard common name:
|
|||
In the example above, a certificate is valid for one hundred years from
|
||||
the date it was created, which is normal for TOFU.
|
||||
.Pp
|
||||
The following is an example of a possible configuration for a site
|
||||
that enables only TLSv1.3, adds the MIME types mapping from
|
||||
.Pa /usr/share/misc/mime.types
|
||||
and defines two virtual host:
|
||||
Then, to run
|
||||
.Nm
|
||||
as a daemon:
|
||||
.Bd -literal -offset indent
|
||||
ipv6 on # enable ipv6
|
||||
|
||||
protocols "tlsv1.3"
|
||||
|
||||
types {
|
||||
include "/usr/share/misc/mime.types"
|
||||
}
|
||||
|
||||
server "example.com" {
|
||||
cert "/etc/ssl/example.com.crt"
|
||||
key "/etc/ssl/private/example.com.key"
|
||||
root "/var/gemini/example.com"
|
||||
}
|
||||
|
||||
server "it.example.com" {
|
||||
cert "/etc/ssl/example.com.crt"
|
||||
key "/etc/ssl/private/example.com.key"
|
||||
root "/var/gemini/it.example.com"
|
||||
|
||||
# enable cgi scripts inside "cgi-bin"
|
||||
cgi "/cgi-bin/*"
|
||||
|
||||
# set the language for text/gemini files
|
||||
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" # absolute path
|
||||
key "/path/to/key.pem" # also absolute
|
||||
root "/example.com" # relative to the chroot
|
||||
|
||||
location "/static/*" {
|
||||
# load the following rules only for
|
||||
# requests that matches "/static/*"
|
||||
|
||||
auto index on
|
||||
index "index.gemini"
|
||||
}
|
||||
}
|
||||
$ gmid -c /etc/gmid.conf
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr gmid.conf 5
|
||||
.Sh ACKNOWLEDGEMENTS
|
||||
.Nm
|
||||
uses the
|
||||
|
|
|
@ -0,0 +1,621 @@
|
|||
.\" Copyright (c) 2022 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: April 7 2022$
|
||||
.Dt GMID.CONF 5
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm gmid.conf
|
||||
.Nd gmid Gemini server configuration file
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
is the configuration file format for the
|
||||
.Xr gmid 1
|
||||
Gemini server.
|
||||
.Pp
|
||||
The configuration file is divided into three sections:
|
||||
.Bl -tag -width xxxx
|
||||
.It Sy Macros
|
||||
User-defined variables may be defined and used later, simplifying the
|
||||
configuration file.
|
||||
.It Sy Global Options
|
||||
Global settings for
|
||||
.Nm .
|
||||
.It Sy Servers
|
||||
Virtual hosts definition.
|
||||
.It Sy Types
|
||||
Media types and extensions.
|
||||
.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 .
|
||||
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
|
||||
.Pp
|
||||
Furthermore, quoting is necessary only when a string needs to contain
|
||||
special characters
|
||||
.Pq like spaces or punctuation ,
|
||||
something that looks like a number or a reserved keyword.
|
||||
The last example could have been written also as:
|
||||
.Bd -literal -offset indent
|
||||
block return 40 temporary "-" failure
|
||||
.Ed
|
||||
.Pp
|
||||
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.
|
||||
.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
|
||||
.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.
|
||||
Macros names may not be reserved words.
|
||||
Macros are not expanded inside quotes.
|
||||
.Pp
|
||||
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
|
||||
For example:
|
||||
.Bd -literal -offset indent
|
||||
dir = "/var/gemini"
|
||||
certdir = "/etc/keys"
|
||||
common = "lang it; auto index on"
|
||||
|
||||
server "foo" {
|
||||
root $dir "/foo" # -> /var/gemini/foo
|
||||
cert $certdir "/foo.pem" # -> /etc/keys/foo.pem
|
||||
key $certdir "/foo.key" # -> /etc/keys/foo.key
|
||||
@common
|
||||
}
|
||||
.Ed
|
||||
.Ss Global Options
|
||||
.Bl -tag -width 12m
|
||||
.It Ic chroot Ar path
|
||||
.Xr chroot 2
|
||||
the process to the given
|
||||
.Ar 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 enforce this.
|
||||
.It Ic ipv6 Ar bool
|
||||
Enable or disable IPv6 support, off by default.
|
||||
.It Ic port Ar portno
|
||||
The port to listen on.
|
||||
1965 by default.
|
||||
.It Ic prefork Ar number
|
||||
Run the specified number of server processes.
|
||||
This increases the performance and prevents delays when connecting to
|
||||
a server.
|
||||
When not in config-less mode,
|
||||
.Nm
|
||||
runs 3 server processes by default.
|
||||
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.
|
||||
It 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 alias Ar name
|
||||
Specify an additional alias
|
||||
.Ar name
|
||||
for this server.
|
||||
.It Ic auto Ic index Ar bool
|
||||
If no index file is found, automatically generate a directory listing.
|
||||
Disabled by default.
|
||||
.It Ic block Op Ic return Ar code Op Ar meta
|
||||
Send a reply and close the connection;
|
||||
by default
|
||||
.Ar code
|
||||
is 40
|
||||
and
|
||||
.Ar meta
|
||||
is
|
||||
.Dq temporary failure .
|
||||
If
|
||||
.Ar code
|
||||
is in the 3x range, then
|
||||
.Ar meta
|
||||
is mandatory.
|
||||
Inside
|
||||
.Ar meta ,
|
||||
the following special sequences are supported:
|
||||
.Bl -tag -width Ds -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 Ar file
|
||||
Path to the certificate to use for this server.
|
||||
.Ar file
|
||||
should contain a PEM encoded certificate.
|
||||
This option is mandatory.
|
||||
.It Ic cgi Ar path
|
||||
Execute
|
||||
.Sx CGI
|
||||
scripts that matches
|
||||
.Ar path
|
||||
using shell globbing rules.
|
||||
.Pp
|
||||
The CGI scripts are executed in the directory they reside and inherit
|
||||
the environment from
|
||||
.Nm gmid
|
||||
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 gmid
|
||||
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.8.3
|
||||
.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_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.
|
||||
.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
|
||||
.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 Ar path
|
||||
Handle all the requests for the current virtual host using the
|
||||
.Sx CGI
|
||||
script at
|
||||
.Ar path ,
|
||||
relative to the current document root.
|
||||
.It Ic env Ar name Cm = Ar value
|
||||
Set the environment variable
|
||||
.Ar name
|
||||
to
|
||||
.Ar value
|
||||
when executing CGI scripts.
|
||||
Can be provided more than once.
|
||||
.\" don't document the "spawn <prog>" form because it probably won't
|
||||
.\" be kept.
|
||||
.It Ic fastcgi Oo Ic tcp Oc Ar socket Oo Cm port Ar port Oc
|
||||
Enable
|
||||
.Sx FastCGI
|
||||
instead of serving files.
|
||||
The
|
||||
.Ar socket
|
||||
can either be a UNIX-domain socket or a TCP socket.
|
||||
If the FastCGI application is listening on a UNIX domain socket,
|
||||
.Ar socket
|
||||
is a local path name within the
|
||||
.Xr chroot 2
|
||||
root directory of
|
||||
.Nm .
|
||||
Otherwise, the
|
||||
.Ic tcp
|
||||
keyword must be provided and
|
||||
.Ar 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.
|
||||
If not specified defaults to 9000.
|
||||
.It Ic index Ar string
|
||||
Set the directory index file.
|
||||
If not specified, it defaults to
|
||||
.Pa index.gmi .
|
||||
.It Ic key Ar file
|
||||
Specify the private key to use for this server.
|
||||
.Ar 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 Ar path Brq ...
|
||||
Specify server configuration rules for a specific location.
|
||||
.Ar 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 alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key ,
|
||||
.Ic location , Ic param No and Ic proxy .
|
||||
.It Ic log Ar bool
|
||||
Enable or disable the logging for the current server or location block.
|
||||
.It Ic param Ar name Cm = Ar value
|
||||
Set the param
|
||||
.Ar name
|
||||
to
|
||||
.Ar value
|
||||
for FastCGI.
|
||||
By default the following variables
|
||||
.Pq parameters
|
||||
are sent, and carry the same semantics as with CGI:
|
||||
.Pp
|
||||
.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
|
||||
.It Ic ocsp Ar file
|
||||
Specify an OCSP response to be stapled during TLS handshakes
|
||||
with this server.
|
||||
The
|
||||
.Ar file
|
||||
should contain a DER-format OCSP response retrieved from an
|
||||
OCSP server for the
|
||||
.Ic cert
|
||||
in use.
|
||||
If the OCSP response in
|
||||
.Ar file
|
||||
is empty, OCSP stapling will not be used.
|
||||
The default is to not use OCSP stapling.
|
||||
.It Ic proxy Oo Cm proto Ar name Oc Oo Cm for-host Ar host : Ns Oo Ar port Oc Oc Brq ...
|
||||
Set up a reverse proxy.
|
||||
The optional matching rules
|
||||
.Cm proto
|
||||
and
|
||||
.Cm for-host
|
||||
can be used to enable proxying only for protocols matching
|
||||
.Ar name
|
||||
.Po Dq gemini
|
||||
by default
|
||||
.Pc
|
||||
and/or whose request IRI matches
|
||||
.Ar host
|
||||
and
|
||||
.Ar port
|
||||
.Pq 1965 by default .
|
||||
Matching happens using shell globbing rules.
|
||||
.Pp
|
||||
In case of multiple matching proxy blocks in the same context, the
|
||||
first matching proxy will be put into effect and the later ones
|
||||
ignored.
|
||||
.Pp
|
||||
Valid options are:
|
||||
.Bl -tag -width Ds
|
||||
.It Ic cert Ar file
|
||||
Specify the client certificate to use when making requests.
|
||||
.It Ic key Ar file
|
||||
Specify the client certificate key to use when making requests.
|
||||
.It Ic protocols Ar string
|
||||
Specify the TLS protocols allowed when making remote requests.
|
||||
Refer to the
|
||||
.Xr tls_config_parse_protocols 3
|
||||
function for the valid protocol string values.
|
||||
By default, both TLSv1.2 and TLSv1.3 are enabled.
|
||||
.It Ic relay-to Ar host : Ns Op Ar port
|
||||
Relay the request to the given
|
||||
.Ar host
|
||||
at the given
|
||||
.Ar port ,
|
||||
1965 by default.
|
||||
This is the only mandatory option in a
|
||||
.Ic proxy
|
||||
block.
|
||||
.It Ic require Ic client Ic ca Ar file
|
||||
Allow the proxying only from clients that provide a certificate
|
||||
signed by the CA certificate in
|
||||
.Ar file .
|
||||
.It Ic sni Ar hostname
|
||||
Use the given
|
||||
.Ar hostname
|
||||
instead of the one extracted from the
|
||||
.Ic relay-to
|
||||
rule for the TLS handshake with the proxied gemini server.
|
||||
.It Ic use-tls Ar bool
|
||||
Specify whether to use TLS when connecting to the proxied host.
|
||||
Enabled by default.
|
||||
.It Ic verifyname Ar bool
|
||||
Enable or disable the TLS server name verification.
|
||||
Enabled by default.
|
||||
.El
|
||||
.It Ic root Ar directory
|
||||
Specify the root directory for this server
|
||||
.Pq alas the current Dq document root .
|
||||
It's relative to the chroot if enabled.
|
||||
.It Ic require Ic client Ic ca Ar path
|
||||
Allow requests only from clients that provide a certificate signed by
|
||||
the CA certificate in
|
||||
.Ar 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 before doing a lookup in the
|
||||
root directory.
|
||||
It's also considered for the
|
||||
.Ar meta
|
||||
parameter in the scope of a
|
||||
.Ic block return .
|
||||
.El
|
||||
.Ss Types
|
||||
The
|
||||
.Ic types
|
||||
section must include one or more lines of the following syntax, enclosed
|
||||
in curly brances:
|
||||
.Bl -tag -width Ds
|
||||
.It Ar type/subtype Ar name Op Ar name ...
|
||||
Set the media
|
||||
.Ar type
|
||||
and
|
||||
.Ar subtype
|
||||
to the specified extension
|
||||
.Ar name .
|
||||
One or more names can be specified per line.
|
||||
Earch line may end with an optional semicolon.
|
||||
.It Ic include Ar file
|
||||
Include types definition from an external file, for example
|
||||
.Pa /usr/share/misc/mime.types .
|
||||
.El
|
||||
.Pp
|
||||
By default
|
||||
.Nm gmid
|
||||
has built-in media types for
|
||||
.Bl -tag -offset indent -width 15m -compact
|
||||
.It application/pdf
|
||||
pdf
|
||||
.It image/gif
|
||||
gif
|
||||
.It image/jpeg
|
||||
jpg
|
||||
.It image/png
|
||||
png
|
||||
.It image/svg+xml
|
||||
svg
|
||||
.It text/gemini
|
||||
gemini gmi
|
||||
.It text/markdown
|
||||
markdown md
|
||||
.It text/x-patch
|
||||
diff patch
|
||||
.It text/xml
|
||||
xml
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
The following is an example of a possible configuration for a site
|
||||
that enables only TLSv1.3, adds the MIME types mapping from
|
||||
.Pa /usr/share/misc/mime.types
|
||||
and defines two virtual host:
|
||||
.Bd -literal -offset indent
|
||||
ipv6 on # enable ipv6
|
||||
|
||||
protocols "tlsv1.3"
|
||||
|
||||
types {
|
||||
include "/usr/share/misc/mime.types"
|
||||
}
|
||||
|
||||
server "example.com" {
|
||||
cert "/etc/ssl/example.com.pem"
|
||||
key "/etc/ssl/private/example.com.key"
|
||||
root "/var/gemini/example.com"
|
||||
}
|
||||
|
||||
server "example.it" {
|
||||
cert "/etc/ssl/example.it.pem"
|
||||
key "/etc/ssl/private/example.it.key"
|
||||
root "/var/gemini/example.it"
|
||||
|
||||
# execute cgi scripts inside "cgi-bin"
|
||||
cgi "/cgi-bin/*"
|
||||
|
||||
# set the language for text/gemini files
|
||||
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" {
|
||||
# absolute paths:
|
||||
cert "/etc/ssl/example.com.pem"
|
||||
key "/etc/ssl/private/example.com.key"
|
||||
|
||||
# relative to the chroot:
|
||||
root "/example.com"
|
||||
|
||||
location "/static/*" {
|
||||
# load the following rules only for
|
||||
# requests that matches "/static/*"
|
||||
|
||||
auto index on
|
||||
index "index.gemini"
|
||||
}
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr gmid 1 ,
|
||||
.Xr slowcgi 8
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
The
|
||||
.Nm gmid
|
||||
program was written by
|
||||
.An Omar Polo Aq Mt op@omarpolo.com .
|
Loading…
Reference in New Issue