💾 Archived View for gmid.omarpolo.com › gmid.conf.5.txt captured on 2022-04-29 at 13:44:51.

View Raw

More Information

⬅️ Previous capture (2022-04-28)

➡️ Next capture (2022-07-16)

-=-=-=-=-=-=-

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

NAME
     gmid.conf	gmid Gemini server configuration file

DESCRIPTION
     gmid.conf is the configuration file format for the gmid(1)
     Gemini server.

     The configuration file is divided into three sections:

     Macros
	   User-defined variables may be defined and used later,
	   simplifying the configuration file.

     Global Options
	   Global settings for gmid.conf.

     Servers
	   Virtual hosts definition.

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

   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.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 bool	   Enable or disable IPv6 support, off by
		   default.

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

	     The CGI scripts are executed in the directory they
	     reside and inherit the environment from gmid with
	     these additional variables set:

	     GATEWAY_INTERFACE	       CGI/1.1

	     GEMINI_DOCUMENT_ROOT      The root directory of the
				       virtual host.

	     GEMINI_SCRIPT_FILENAME    Full path to the CGI
				       script being executed.

	     GEMINI_URL		       The full IRI of the
				       request.

	     GEMINI_URL_PATH	       The path of the request.

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

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

	     QUERY_STRING	       The decoded query 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 the
				       empty string.

	     SCRIPT_NAME	       The part of the
				       GEMINI_URL_PATH that
				       identifies the current CGI
				       script.

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

	     AUTH_TYPE		       The string "Certificate"
				       if the client used a
				       certificate, otherwise
				       unset.

	     REMOTE_USER	       The subject of the client
				       certificate if provided,
				       otherwise unset.

	     TLS_CLIENT_ISSUER	       The is 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.

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

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

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

SEE ALSO
     gmid(1), slowcgi(8)

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

OpenBSD 7.1		  April 7, 2022		      OpenBSD 7.1