Macros

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.crt" # -> /etc/keys/foo.crt
	key  $certdir "/foo.pem" # -> /etc/keys/foo.pem
	@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 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 may enforce this.

ipv6 bool

Enable or disable IPv6 support, off by default.

map mime-type to-ext file-extension

Map mime-type to the given file-extension. Both argument are strings.

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

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.

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

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

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.