GMID.CONF(5) File Formats Manual GMID.CONF(5)

gmid.confgmid 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:

User-defined variables may be defined and used later, simplifying the configuration file.
Global settings for gmid.conf.
Virtual hosts definition.
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 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
}

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.
bool
Enable or disable IPv6 support, off by default.
portno
The port to listen on. 1965 by default.
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.
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.
string
Run the daemon as the given user.

Every virtual host is defined by a server block:

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:

name
Specify an additional alias name for this server.
index bool
If no index file is found, automatically generate a directory listing. Disabled by default.
[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.
file
Path to the certificate to use for this server. file should contain a PEM encoded certificate. This option is mandatory.
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:

“CGI/1.1”
The root directory of the virtual host.
Full path to the CGI script being executed.
The full IRI of the request.
The path of the request.
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.
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.
The decoded query string.
, REMOTE_HOST
Textual representation of the client IP.
This is present only for RFC3875 (CGI) compliance. It's always set to the empty string.
The part of the GEMINI_URL_PATH that identifies the current CGI script.
The name of the server
The port the server is listening on.
“GEMINI”
The name and version of the server, i.e. “gmid/1.8.4”
The string "Certificate" if the client used a certificate, otherwise unset.
The subject of the client certificate if provided, otherwise unset.
The is the issuer of the client certificate if provided, otherwise unset.
The hash of the client certificate if provided, otherwise unset. The format is “ALGO:HASH”.
The TLS version negotiated with the peer.
The cipher suite negotiated with the peer.
The strength in bits for the symmetric cipher that is being used with the peer.
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”).
The time corresponding to the start of the validity period of the peer certificate in the ISO 8601 format.
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”.
path
Handle all the requests for the current virtual host using the CGI script at path, relative to the current document root.
name = value
Set the environment variable name to value when executing CGI scripts. Can be provided more than once.
[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.
string
Set the directory index file. If not specified, it defaults to index.gmi.
file
Specify the private key to use for this server. file should contain a PEM encoded private key. This option is mandatory.
string
Specify the language tag for the text/gemini content served. If not specified, no “lang” parameter will be added in the response.
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.
bool
Enable or disable the logging for the current server or location block.
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
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.
[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:

file
Specify the client certificate to use when making requests.
file
Specify the client certificate key to use when making requests.
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.
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.
client ca file
Allow the proxying only from clients that provide a certificate signed by the CA certificate in file.
hostname
Use the given hostname instead of the one extracted from the relay-to rule for the TLS handshake with the proxied gemini server.
bool
Specify whether to use TLS when connecting to the proxied host. Enabled by default.
bool
Enable or disable the TLS server name verification. Enabled by default.
directory
Specify the root directory for this server (alas the current “document root”). It's relative to the chroot if enabled.
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.
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.

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.
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.

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"
	}
}

gmid(1), slowcgi(8)

The gmid program was written by Omar Polo <op@omarpolo.com>.

April 7, 2022 OpenBSD 7.1