GMID.CONF(5)

📦 version 2.1.1, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

gmid.conf(5) — from the File Formats Manual, bestie — gmid.conf is the gmid Gemini server configuration file. 💅

✨ DESCRIPTION ✨

Okay so gmid.conf is literally the configuration file format for the gmid(8) Gemini server. It's giving four sections, bestie:

  • Macros — user-defined variables may be defined and used later, simplifying the configuration file. 🧚
  • Global Options — global settings for gmid(8). 🌈
  • Types — media types and extensions. 🎀
  • Servers — virtual hosts definition. 👑

Inside those 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 it's possible to mix macros, options and server blocks — slay, no cap. However, defining all the server blocks after the macros and the global options is recommended, periodt. 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"

Obsessed. 💖

🧚 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. Macro names may not be reserved words. Macros are not expanded inside quotes. Not even a little.

Two kinds of macros are supported: variable-like and proper macros. When a macro is invoked with a $ before its name, it's expanded as a string, whereas when it's invoked with a @, it's expanded in-place.

For example:

ext_ip = "10.0.0.1"
dir = "/var/gemini"
certdir = "/etc/keys"
common = "lang it; auto index on"

server "foo" {
        listen on $ext_ip
        root $dir "/foo"         # "/var/gemini/foo"
        cert $certdir "/foo.pem" # "/etc/keys/foo.pem"
        key  $certdir "/foo.key" # "/etc/keys/foo.key"
        @common
}

This example ate, honestly. 🫶

🌈 Global Options 🌈

  • chroot path — chroot(2) the process to the given path. ngl, the daemon has to be run with root privileges and thus the option user needs to be provided too, so privileges can be dropped afterwards. The way that paths work here: all the paths in the configuration file are relative to the chroot directory, except for the cert, key and ocsp paths. Defaults to the user home directory, if provided.
  • log options — Specify logging options. Multiple options may be provided within curly braces. The available options are as follows:
    • access file — Log the requests to file. The path is relative to the chroot.
    • style style — Set the logging style, defaults to legacy. The style can be one of:
      • common — Attempt to be compatible with the default Apache httpd log format. Each line is formatted as follows: the matching host name, the remote IP address, one dash -, Common Name of the client certificate (if provided, '-' otherwise), the timestamp of the request, the request URI wrapped in double quotes, the response code and the size of the response.
      • combined — Attempt to be compatible with the default nginx log format. Each line is formatted as follows: the remote IP address, one dash -, Common Name of the client certificate (if provided, '-' otherwise), the timestamp wrapped in square brackets, the request URI wrapped in double quotes, the response code, the size of the response, a dash wrapped in double quotes and "". The strangeness of these two last fields is because Gemini doesn't have the notion of the Referer header nor the User-agent.
      • legacy — Each line is formatted as follows: the remote IP address and port, the GET keyword, the request URI, the response code and meta.
    • syslog [off] — Log to syslog. It is enabled by default, use the off argument to disable.
    • syslog facility facility — Log to syslog(3) using specified facility. Available facilities are as follows: daemon, ftp, local0 through local7 and user. These are case insensitive and can be prefixed with LOG_. Not all level may be available on all operating systems. The default facility is LOG_DAEMON. iykyk.
  • prefork number — Run the specified number of server processes. This increases the performance and prevents delays when connecting to a server. gmid(8) 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. Mandatory if the chroot option is used.

👑 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 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. vibe check: off unless you say otherwise, no cap.
  • 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. Main character energy, fr fr.
  • 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".
  • fastcgi option — Enable FastCGI instead of serving files. Multiple options may be specified within curly braces. Valid options are:
    • param name = value — Set the param name to value.
    • socket [tcp] socket [port port] — 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(8). 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.
    • strip number — Strip number leading path components from the request URL before splitting it in SCRIPT_NAME and PATH_INFO.

The FastCGI handler will be given the following variables by default:

  • GEMINI_URL_PATH — Full 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.
  • GATEWAY_INTERFACE — "CGI/1.1".
  • AUTH_TYPE — The string "Certificate" if the client used a certificate, otherwise unset.
  • PATH_INFO — The portion of the requested path that is derived from the IRI path hierarchy following SCRIPT_NAME. Can be unset.
  • PATH_TRANSLATED — Present if and only if PATH_INFO is set. It represents 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 "GET".

okay so the CGI environment variables, bestie — gmid hands these to your script and they're lowkey essential 👑

  • SCRIPT_NAME — the virtual URI path to the script. since it's impossible to determine the correct SCRIPT_NAME programmatically in all cases, gmid assumes it's the empty string. it is recommended to manually specify this parameter when serving a sub-tree of a virtual host via FastCGI 💅
  • 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/2.1.1.
  • REMOTE_USER — the subject of the client certificate if provided, otherwise unset.
  • TLS_CLIENT_ISSUER — 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.
  • fastcgi off — disable FastCGI handling in the current location 🚫
  • 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.
  • listen on address [port number] [proxy-v1] — set the listen address and port, which defaults to 1965. this statement can be specified multiple times. if address is * then gmid(8) will listen on all IPv4 and IPv6 addresses. 0.0.0.0 can be used to listen on all IPv4 addresses and :: on all IPv6 addresses. if proxy-v1 is specified, then connections speaking the proxy protocol v1 are expected on this listener. if multiple listen directives share the same address and port, then all of them must have or lack proxy-v1 ⚠️
  • 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 it 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, key, listen, location and proxy.
  • log bool — enable or disable the logging for the current server or location block.
  • 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 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.
    • proxy-v1 — use the proxy protocol v1. if supported by the remote server, this is useful to propagate the information about the originating IP address and port.
    • relay-to host [port 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 (yes bestie, 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. each 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 🌸

here's a config for a site that enables only TLSv1.3, adds the MIME types mapping from /usr/share/misc/mime.types, and defines two virtual hosts:

             protocols "tlsv1.3"

             types {
                     include "/usr/share/misc/mime.types"
             }

             server "example.com" {
                     listen on * port 1965
                     cert "/etc/ssl/example.com.pem"
                     key  "/etc/ssl/private/example.com.key"
                     root "/var/gemini/example.com"
             }

             server "example.it" {
                     listen on * port 1965
                     cert "/etc/ssl/example.it.pem"
                     key  "/etc/ssl/private/example.it.key"
                     root "/var/gemini/example.it"

                     # set the language for text/gemini files
                     lang "it"
             }

this example shows how to enable the chroot and use a location rule:

             chroot "/var/gemini"
             user "_gmid"

             server "example.com" {
                     listen on * port 1965

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

this example shows how to log requests to /var/gemini/logs/access.log when running in the /var/gemini chroot. the file will be created if it does not exist:

             chroot "/var/gemini"
             user "_gmid"

             log {
                     access "/logs/access.log"  # relative to the chroot
             }

and this example shows how to set up a reverse proxy: all requests for example.com will be forwarded to 10.0.0.6 transparently. proxying establishes a new TLS connection, so any client-certificates used to connect to gmid(8) cannot be provided to the proxied server:

             server "example.com" {
                     listen on * port 1965
                     cert "/etc/ssl/example.com.pem"
                     key "/etc/ssl/private/example.com.key"
                     proxy {
                             relay-to 10.0.0.6 port 1965
                     }
             }

🔥 SEE ALSO 🔥

👑 AUTHORS 👑

the gmid program was written by Omar Polo <op@omarpolo.com>. periodt 💅

that's the whole page, bestie 🫶 — it's from Debian, dated August 25, 2024, and it's GMID.CONF(5) ✨

📦 where this page comes from