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_INTERFACE
GEMINI_DOCUMENT_ROOT
GEMINI_SCRIPT_FILENAME
GEMINI_URL
GEMINI_URL_PATH
PATH_INFO
PATH_TRANSLATED
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
REMOTE_ADDR
,
REMOTE_HOST
REQUEST_METHOD
SCRIPT_NAME
GEMINI_URL_PATH
that
identifies the current CGI script.SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
AUTH_TYPE
REMOTE_USER
TLS_CLIENT_ISSUER
TLS_CLIENT_HASH
TLS_VERSION
TLS_CIPHER
TLS_CIPHER_STRENGTH
TLS_CLIENT_NOT_AFTER
TLS_CLIENT_NOT_BEFORE
default
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 |