| GMID.CONF(5) | File Formats Manual | GMID.CONF(5) |
gmid.conf — gmid
Gemini server configuration file
gmid.conf is the configuration file format
for the gmid(1) Gemini server.
The configuration file is divided into three sections:
gmid.conf.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 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
}
chroot
pathuser 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
boolport
portnoprefork
numbergmid.conf runs 3 server
processes by default. The maximum number allowed is 16.protocols
stringuser
stringEvery virtual host is defined by a server
block:
server
hostname {...}Followed by a block of options that is enclosed in curly brackets:
alias
nameauto
index boolblock
[return code
[meta]]cert
filecgi
pathThe CGI scripts are executed in the directory they reside and
inherit the environment from gmid with these
additional variables set:
GATEWAY_INTERFACEGEMINI_DOCUMENT_ROOTGEMINI_SCRIPT_FILENAMEGEMINI_URLGEMINI_URL_PATHPATH_INFOPATH_TRANSLATEDPATH_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_STRINGREMOTE_ADDR,
REMOTE_HOSTREQUEST_METHODSCRIPT_NAMEGEMINI_URL_PATH that
identifies the current CGI script.SERVER_NAMESERVER_PORTSERVER_PROTOCOLSERVER_SOFTWAREAUTH_TYPEREMOTE_USERTLS_CLIENT_ISSUERTLS_CLIENT_HASHTLS_VERSIONTLS_CIPHERTLS_CIPHER_STRENGTHTLS_CLIENT_NOT_AFTERTLS_CLIENT_NOT_BEFOREdefault
type stringdefault
type is set to “application/octet-stream”.entrypoint
pathenv
name =
valuefastcgi
[tcp] socket
[port port]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
stringkey
filelang
stringlocation
path {...}location section may include most of the server
configuration rules except alias,
cert, cgi,
entrypoint, env,
key, location,
param and
proxy.log
boolparam
name =
valueocsp
filecert 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]] {...}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
filekey
fileprotocols
stringrelay-to
host:[port]proxy block.require
client ca
filesni
hostnamerelay-to rule for the TLS
handshake with the proxied gemini server.use-tls
boolverifyname
boolroot
directoryrequire
client ca
pathstrip
numberblock return.The types section must include one or more
lines of the following syntax, enclosed in curly brances:
include
fileBy default gmid uses the following mapping
if no types block is defined:
As an exception, gmid uses the MIME type
text/gemini for file extensions
gemini or gmi if no mapping was
found.
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"
}
}
The gmid program was written by
Omar Polo
<op@omarpolo.com>.
| April 7, 2022 | OpenBSD 7.1 |