💾 Archived View for gmid.omarpolo.com › gmid.conf.5.txt captured on 2023-07-10 at 13:24:59.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
GMID.CONF(5) File Formats Manual GMID.CONF(5)
NAME
gmid.conf gmid Gemini server configuration file
DESCRIPTION
gmid.conf is the configuration file format for the gmid(1)
Gemini server.
The configuration file is divided into three sections:
Macros
User-defined variables may be defined and used later,
simplifying the configuration file.
Global Options
Global settings for gmid.conf.
Servers
Virtual hosts definition.
Types
Media types and extensions.
Within the sections, empty lines are ignored and comments
can be put anywhere in the file using a hash mark (#), and
extend to the end of the current line. A boolean is either
the symbol on or off. A string is a sequence of
characters wrapped in double quotes, like this. Multiple
strings one next to the other are joined into a single
string:
# equivalent to "temporary-failure"
block return 40 "temporary" "-" "failure"
Furthermore, quoting is necessary only when a string needs
to contain special characters (like spaces or punctuation),
something that looks like a number or a reserved keyword.
The last example could have been written also as:
block return 40 temporary "-" failure
Strict ordering of the sections is not enforced, so that is
possible to mix macros, options and server blocks. However,
defining all the server blocks after the macros and the
global options is recommended.
Newlines are often optional, except around top-level
instructions, and semicolons ; can also be optionally used
to separate options.
Additional configuration files can be included with the
include keyword, for example:
include "/etc/gmid.conf.local"
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.
Two kinds of macros are supported: variable-like and proper
macros. When a macro is invoked with a $ before its name
its expanded as a string, whereas when it's invoked with a
@ its expanded in-place.
For example:
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
}
Global Options
chroot path chroot(2) the process to the given path. The
daemon has to be run with root privileges and
thus the option user needs to be provided, so
privileges can be dropped. Note that
gmid.conf 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 gmid.conf may enforce this.
ipv6 bool Enable or disable IPv6 support, off by
default.
port portno The port to listen on. 1965 by default.
prefork 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, gmid.conf runs 3 server
processes by default. The maximum number
allowed is 16.
protocols string
Specify the TLS protocols to enable. Refer to
tls_config_parse_protocols(3) for the valid
protocol string values. By default, both
TLSv1.3 and TLSv1.2 are enabled. Use
tlsv1.3 to enable only TLSv1.3.
user string Run the daemon as the given user.
Servers
Every virtual host is defined by a server block:
server hostname {...}
Match the server name using shell globbing rules.
It can be an explicit name, www.example.com, or a
name including a wildcards, *.example.com.
Followed by a block of options that is enclosed in curly
brackets:
alias name
Specify an additional alias name for this server.
auto index bool
If no index file is found, automatically generate a
directory listing. Disabled by default.
block [return code [meta]]
Send a reply and close the connection; by default
code is 40 and meta is temporary failure. If code
is in the 3x range, then meta is mandatory. Inside
meta, the following special sequences are supported:
%% is replaced with a single %.
%p is replaced with the request path.
%q is replaced with the query string of the
request.
%P is replaced with the server port.
%N is replaced with the server name.
cert file
Path to the certificate to use for this server.
file should contain a PEM encoded certificate. This
option is mandatory.
cgi path
Execute CGI scripts that matches path using shell
globbing rules.
The CGI scripts are executed in the directory they
reside and inherit the environment from gmid with
these additional variables set:
GATEWAY_INTERFACE CGI/1.1
GEMINI_DOCUMENT_ROOT The root directory of the
virtual host.
GEMINI_SCRIPT_FILENAME Full path to the CGI
script being executed.
GEMINI_URL The full IRI of the
request.
GEMINI_URL_PATH The path of the request.
GEMINI_SEARCH_STRING The decoded QUERY_STRING
if defined in the request
and if it doesn't contain
any unencoded =
characters, otherwise
unset.
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.
PATH_TRANSLATED Present if and only if
PATH_INFO is set. It
represent the translation
of the PATH_INFO. gmid
builds this by appending
the PATH_INFO to the
virtual host directory
root.
QUERY_STRING The URL-encoded search or
parameter string.
REMOTE_ADDR, REMOTE_HOST Textual representation of
the client IP.
REQUEST_METHOD This is present only for
RFC3875 (CGI) compliance.
It's always set to the
empty string.
SCRIPT_NAME The part of the
GEMINI_URL_PATH that
identifies the current CGI
script.
SERVER_NAME The name of the server
SERVER_PORT The port the server is
listening on.
SERVER_PROTOCOL GEMINI
SERVER_SOFTWARE The name and version of
the server, i.e.
gmid/1.8.6
AUTH_TYPE The string "Certificate"
if the client used a
certificate, otherwise
unset.
REMOTE_USER The subject of the client
certificate if provided,
otherwise unset.
TLS_CLIENT_ISSUER The is the issuer of the
client certificate if
provided, otherwise unset.
TLS_CLIENT_HASH The hash of the client
certificate if provided,
otherwise unset. The
format is ALGO:HASH.
TLS_VERSION The TLS version negotiated
with the peer.
TLS_CIPHER The cipher suite
negotiated with the peer.
TLS_CIPHER_STRENGTH The strength in bits for
the symmetric cipher that
is being used with the
peer.
TLS_CLIENT_NOT_AFTER The time corresponding to
the end of the validity
period of the peer
certificate in the ISO
8601 format (e.g.
2021-02-07T20:17:41Z).
TLS_CLIENT_NOT_BEFORE The time corresponding to
the start of the validity
period of the peer
certificate in the ISO
8601 format.
default type string
Set the default media type that is used if the media
type for a specified extension is not found. If not
specified, the default type is set to
application/octet-stream.
entrypoint path
Handle all the requests for the current virtual host
using the CGI script at path, relative to the
current document root.
env name = value
Set the environment variable name to value when
executing CGI scripts. Can be provided more than
once.
fastcgi [tcp] socket [port port]
Enable FastCGI instead of serving files. The socket
can either be a UNIX-domain socket or a TCP socket.
If the FastCGI application is listening on a UNIX
domain socket, socket is a local path name within
the chroot(2) root directory of gmid.conf.
Otherwise, the tcp keyword must be provided and
socket is interpreted as a hostname or an IP
address. port can be either a port number or the
name of a service enclosed in double quotes. If not
specified defaults to 9000.
index string
Set the directory index file. If not specified, it
defaults to index.gmi.
key file
Specify the private key to use for this server.
file should contain a PEM encoded private key. This
option is mandatory.
lang string
Specify the language tag for the text/gemini content
served. If not specified, no lang parameter will
be added in the response.
location path {...}
Specify server configuration rules for a specific
location. 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 location section may
include most of the server configuration rules
except alias, cert, cgi, entrypoint, env, key,
location, param and proxy.
log bool
Enable or disable the logging for the current server
or location block.
param name = value
Set the param name to value for FastCGI. By default
the following variables (parameters) are sent, and
carry the same semantics as with CGI:
GATEWAY_INTERFACE
GEMINI_URL_PATH
QUERY_STRING
REMOTE_ADDR
REMOTE_HOST
REQUEST_METHOD
SERVER_NAME
SERVER_PROTOCOL
SERVER_SOFTWARE
AUTH_TYPE
REMOTE_USER
TLS_CLIENT_ISSUER
TLS_CLIENT_HASH
TLS_VERSION
TLS_CIPHER
TLS_CIPHER_STRENGTH
TLS_CLIENT_NOT_BEFORE
TLS_CLIENT_NOT_AFTER
ocsp file
Specify an OCSP response to be stapled during TLS
handshakes with this server. The file should
contain a DER-format OCSP response retrieved from an
OCSP server for the cert in use. If the OCSP
response in file is empty, OCSP stapling will not be
used. The default is to not use OCSP stapling.
proxy [proto name] [for-host host:[port]] {...}
Set up a reverse proxy. The optional matching rules
proto and for-host can be used to enable proxying
only for protocols matching name (gemini by
default) and/or whose request IRI matches host and
port (1965 by default). Matching happens using
shell globbing rules.
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.
Valid options are:
cert file
Specify the client certificate to use when
making requests.
key file
Specify the client certificate key to use
when making requests.
protocols string
Specify the TLS protocols allowed when
making remote requests. Refer to the
tls_config_parse_protocols(3) function for
the valid protocol string values. By
default, both TLSv1.2 and TLSv1.3 are
enabled.
relay-to host:[port]
Relay the request to the given host at the
given port, 1965 by default. This is the
only mandatory option in a proxy block.
require client ca file
Allow the proxying only from clients that
provide a certificate signed by the CA
certificate in file.
sni hostname
Use the given hostname instead of the one
extracted from the relay-to rule for the TLS
handshake with the proxied gemini server.
use-tls bool
Specify whether to use TLS when connecting
to the proxied host. Enabled by default.
verifyname bool
Enable or disable the TLS server name
verification. Enabled by default.
root directory
Specify the root directory for this server (alas the
current document root). It's relative to the
chroot if enabled.
require client ca path
Allow requests only from clients that provide a
certificate signed by the CA certificate in path.
It needs to be a PEM-encoded certificate and it's
not relative to the chroot.
strip number
Strip number components from the beginning of the
path before doing a lookup in the root directory.
It's also considered for the meta parameter in the
scope of a block return.
Types
The types section must include one or more lines of the
following syntax, enclosed in curly brances:
type/subtype name [name ...]
Set the media type and subtype to the specified
extension name. One or more names can be specified
per line. Earch line may end with an optional
semicolon.
include file
Include types definition from an external file, for
example /usr/share/misc/mime.types.
By default gmid uses the following mapping if no types block
is defined:
application/pdf pdf
image/gif gif
image/jpeg jpg jpeg
image/png png
image/svg+xml svg
text/gemini gemini gmi
text/markdown markdown md
text/x-patch diff patch
text/xml xml
As an exception, gmid uses the MIME type text/gemini for
file extensions gemini or gmi if no mapping was found.
EXAMPLES
The following is an example of a possible configuration for
a site that enables only TLSv1.3, adds the MIME types
mapping from /usr/share/misc/mime.types and defines two
virtual host:
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"
}
Yet another example, showing how to enable a chroot and use
location rule
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"
}
}
SEE ALSO
gmid(1), slowcgi(8)
AUTHORS
The gmid program was written by Omar Polo <op@omarpolo.com>.
OpenBSD 7.2 December 2, 2022 OpenBSD 7.2