gmnisrv.ini(5) # NAME *gmnisrv.ini* - configuration file for *gmnisrv*(1) # SYNTAX *gmnisrv.ini* is an INI file. Each line is either a key/value pair, or a section heading. Key/value pairs are specified as key=value, and sections as [section]. # CONFIGURATION KEYS The meaning of the key depends on the section. Anonymous keys (prior to the first [section] directive) are used to specify parameters for the daemon itself. Sections whose name is prefixed with ":", e.g. [:tls], are sub-categories of the daemon configuration. Otherwise, section names refer to the hostnames of domains serviced by the *gmnisrv* daemon. ## ANONYMOUS KEYS *listen* A space-separated list of addresses that the daemon shall bind to. Each address shall take the format *address*:*port*. If :*port* is omitted, 1965 (the default Gemini port) is presumed. To specify an IPv6 address, enclose it in *[]*, e.g. *[::]*. ## TLS KEYS The following keys are accepted under the *[:tls]* section: *store* Path to the certificate store on disk. This should be a persistent directory writable by the daemon. The daemon manages its own certificates - no user intervention is required, except in the case of moving the daemon to another host, in which case the certificate store must be copied to the new host. *organization* An optional key used during certificate generation. Fill this in with the name of the organization responsible for the host and it will be filled in as the X.509 /O name. ## ROUTING KEYS To configure *gmnisrv* to service requests, routing keys must be defined. The name of the configuration section is used to determine what kinds of requests it configures. The format of the section name is the _hostname_ to be serviced, followed by a token which defines the routing strategy, and a _string_ whose format is specific to each routing strategy. The token and match string may be omitted (i.e. [_hostname_] alone), which implies path routing against "/". |] *:* :< Route by path prefix. The URL path is compared to "_string_/". | *=* : Exact match. The URL path must exactly match the _string_. | *~* : Regular expression routing. The _string_ is a JavaScript-compatible regular expression which is tested against the URL path. See ECMAScript 2018 (ECMA-282, 9th Edition), section 21.2 for a definition of the regular expression syntax and features, or an informative reference on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions Some example section names and examples of matching paths: |[ *[example.org:/foo]* :< /foo, /foo/bar, /foo/bar/baz | *[example.org=/foo.txt]* : /foo.txt | *[example.org~/[a-z]+\\.(png|jpg|webp)* : /foo.png, /bar.webp Routes should be ordered from least to most specific. The matching algorithm attempts to match the URL against each route in reverse order, and chooses the first route which matches. Within each routing section, the following keys are used to configure how *gmnisrv* will respond to matching requests: *root* Configures the path on disk from which files shall be served for this host. The path component of the URL will be appended to this value to form the path to files on disk to serve. If example.org/foo/bar.txt is requested, and a route is configured for *[example.org:/foo]* with the root set to /srv/gemini, /srv/gemini/foo/bar.txt will be served. *rewrite* If regular expression routing is used, the rewrite directive may be used to rewrite the URL path component before proceeding. The URL will be set to the value of the rewrite expression. If *\\N* appears in the rewrite value, where *N* is a number, that capture group will be substituted for *\\N*. If *\\{name}* appears, where *name* is a named capture group, it will be substituted. Example: ``` [localhost~^/([a-zA-Z]+)\.(?png|jpg)$] root=./root rewrite=/images/\1.\{extension} ``` This will rewrite a request for /example.png to /images/example.png. *index* Configures the name of the index file which shall be served in the event that a request for this host does not include the filename part. Defaults to "index.gmi". *autoindex* "on" to enable the auto-index feature, which presents clients with a list of files in the requested directory when an index file cannot be found. Off by default. *cgi* "on" to enable CGI support. *root* must also be configured. See "CGI Support" for details. # CGI Support *gmnisrv* supports a limited version of CGI, compatible with the Jetforce server. It is not a faithful implementation of RFC 3875, but is sufficient for most of the needs of Gemini servers. Set *cgi=on* for a route configuration to enable CGI for that route and set *root* to the path where the CGI scripts are found. If a client requests a script, it will be executed, and must print a Gemini response (including status code and meta) to stdout. The following environment variables will be set: [[ *Variable* :[ *Example* :< *Description* | *GATEWAY_INTERFACE* : CGI/1.1 : CGI version | *SERVER_PROTOCOL* : GEMINI : The server protocol | *SERVER_SOFTWARE* : gmnisrv/0.0.0 : The gmnisrv server name and version | *GEMINI_URL* : See [1] : The URL requested by the client | *SCRIPT_NAME* : /cgi-bin/foo.sh : The portion of the URL referring to the script name. | *PATH_INFO* : /bar : The remainder of the path following *SCRIPT_NAME*. | *QUERY_STRING* : hello=world : The query string portion of the URL. | *SERVER_NAME*, *HOSTNAME* : example.org : The server host name. | *SERVER_PORT* : 1965 : The server port number. | *REMOTE_HOST*, *REMOTE_ADDR* : 10.10.0.2 : The clients IP address. | *TLS_CIPHER* : TLS_AES_256_GCM_SHA384 : The negotiated TLS cipher. | *TLS_VERSION* : TLSv1.3 : The negotiated TLS version. | *AUTH_TYPE* : CERTIFICATE : Compatibility with RFC 3785. | *TLS_CLIENT_HASH* : SHA256:BD3A388021A92017B781504A3D24F324BF9DE11CE72606AB445D98A8EB00C5A8 : Unique fingerprint of the client certificate. \[1]: gemini://example.org/cgi-bin/foo.sh/bar?hello=world The exit status of the script is ignored.