.\" Copyright (c) 2021 Omar Polo .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .Dd $Mdocdate: July 29 2021$ .Dt GMID 1 .Os .Sh NAME .Nm gmid .Nd simple and secure Gemini server .Sh SYNOPSIS .Nm .Bk -words .Op Fl fnv .Op Fl c Ar config .Op Fl D Ar macro Ns = Ns Ar value .Op Fl P Ar pidfile .Ek .Nm .Bk -words .Op Fl 6hVv .Op Fl d Pa certs-dir .Op Fl H Ar hostname .Op Fl p Ar port .Op Fl x Pa cgi .Op Pa dir .Ek .Sh DESCRIPTION .Nm is a simple and minimal gemini server that can serve static files, execute CGI scripts and talk to FastCGI applications. It can run without a configuration file with a limited set of features available. .Pp .Nm rereads the configuration file when it receives .Dv SIGHUP . .Pp The options are as follows: .Bl -tag -width 14m .It Fl c Pa config Specify the configuration file. .It Fl D Ar macro Ns = Ns Ar value Define .Ar macro to be set to .Ar value on the command line. Overrides the definition of .Ar macro in the config file if present. .It Fl f Stays and logs on the foreground. .It Fl n Check that the configuration is valid, but don't start the server. If specified two or more time, dump the configuration in addition to verify it. .It Fl P Pa pidfile Write daemon's pid to the given location. .Ar pidfile will also act as lock: if another process is holding a lock on that file, .Nm will refuse to start. .El .Pp If no configuration file is given, .Nm runs in .Dq config-less mode .Pq i.e. runs in the foreground to serve a directory from the shell and looks for the following options .Bl -tag -width 14m .It Fl 6 Enable IPv6. .It Fl d Pa certs-path Directory where certificates for the config-less mode are stored. By default it is .Pa $XDG_DATA_HOME/gmid , i.e. .Pa ~/.local/share/gmid . .It Fl H Ar hostname The hostname .Po .Ar localhost by default .Pc . Certificates for the given .Ar hostname are searched inside the .Pa certs-dir directory given with the .Fl d option. They have the form .Pa hostname.cert.pem and .Pa hostname.key.pem . If a certificate or a key doesn't exist for a given hostname, they will be generated automatically. .It Fl h , Fl -help Print the usage and exit. .It Fl p Ar port The port to listen on, by default 1965. .It Fl V , Fl -version Print the version and exit. .It Fl v Verbose mode. Multiple .Fl v options increase the verbosity. .It Fl x Pa path Enable execution of .Sx CGI scripts. See the description of the .Ic cgi option in the .Sq Servers section below to learn how .Pa path is processed. Cannot be provided more than once. .It Pa dir The root directory to serve. By default the current working directory is assumed. .El .Sh CONFIGURATION FILE The configuration file is divided into three sections: .Bl -tag -width xxxx .It Sy Macros User-defined variables may be defined and used later, simplifying the configuration file. .It Sy Global Options Global settings for .Nm . .It Sy Servers Virtual hosts definition. .El .Pp Within the sections, empty lines are ignored and comments can be put anywhere in the file using a hash mark .Pq Sq # , and extend to the end of the current line. A boolean is either the symbol .Sq on or .Sq off . A string is a sequence of characters wrapped in double quotes, .Dq like this . Multiple strings one next to the other are joined into a single string: .Bd -literal -offset indent # equivalent to "temporary-failure" block return 40 "temporary" "-" "failure" .Ed .Pp Furthermore, quoting is necessary only when a string needs to contain special characters .Pq like spaces or punctuation , something that looks like a number or a reserved keyword. The last example could have been written also as: .Bd -literal -offset indent block return 40 temporary "-" failure .Ed .Pp Strict ordering of the sections is not enforced, so that is possible to mix macros, options and .Ic server blocks. However, defining all the .Ic server blocks after the macros and the global options is recommended. .Pp Newlines are often optional, except around top-level instructions, and semicolons .Dq \&; can also be optionally used to separate options. .Pp Additional configuration files can be included with the .Ic include keyword, for example: .Bd -literal -offset indent include "/etc/gmid.conf.local" .Ed .Ss 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. .Pp Two kinds of macros are supported: variable-like and proper macros. When a macro is invoked with a .Dq $ before its name its expanded as a string, whereas when it's invoked with a .Dq @ its expanded in-place. .Pp For example: .Bd -literal -offset indent 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 } .Ed .Ss Global Options .Bl -tag -width 12m .It Ic chroot Pa path .Xr chroot 2 the process to the given .Pa path . The daemon has to be run with root privileges and thus the option .Ic user needs to be provided, so privileges can be dropped. Note that .Nm 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 .Nm may enforce this. .It Ic ipv6 Ar bool Enable or disable IPv6 support, off by default. .It Ic map Ar mime-type Cm to-ext Ar file-extension Map .Ar mime-type to the given .Ar file-extension . Both argument are strings. .It Ic port Ar portno The port to listen on. 1965 by default. .It Ic prefork Ar 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, .Nm runs 3 server processes by default. The maximum number allowed is 16. .It Ic protocols Ar string Specify the TLS protocols to enable. Refer to .Xr tls_config_parse_protocols 3 for the valid protocol string values. By default, both TLSv1.3 and TLSv1.2 are enabled. Use .Dq tlsv1.3 to enable only TLSv1.3. .It Ic user Ar string Run the daemon as the given user. .El .Ss Servers Every virtual host is defined by a .Ic server block: .Bl -tag -width Ds .It Ic server Ar hostname Brq ... Match the server name using shell globbing rules. It can be an explicit name, .Ar www.example.com , or a name including a wildcards, .Ar *.example.com . .El .Pp Followed by a block of options that is enclosed in curly brackets: .Bl -tag -width Ds .It Ic alias Ar name Specify an additional alias .Ar name for this server. .It Ic auto Ic index Ar bool If no index file is found, automatically generate a directory listing. Disabled by default. .It Ic block Op Ic return Ar code Op Ar meta Send a reply and close the connection; by default .Ar code is 40 and .Ar meta is .Dq temporary failure . If .Ar code is in the 3x range, then .Ar meta is mandatory. Inside .Ar meta , the following special sequences are supported: .Bl -tag -width Ds -compact .It \&%\&% is replaced with a single .Sq \&% . .It \&%p is replaced with the request path. .It \&%q is replaced with the query string of the request. .It \&%P is replaced with the server port. .It \&%N is replaced with the server name. .El .It Ic cert Pa file Path to the certificate to use for this server. The .Pa file should contain a PEM encoded certificate. This option is mandatory. .It Ic cgi Pa path Execute .Sx CGI scripts that matches .Pa path using shell globbing rules. .It Ic default type Ar string Set the default media type that is used if the media type for a specified extension is not found. If not specified, the .Ic default type is set to .Dq application/octet-stream . .It Ic entrypoint Pa path Handle all the requests for the current virtual host using the .Sx CGI script at .Pa path , relative to the current document root. .It Ic env Ar name Cm = Ar value Set the environment variable .Ar name to .Ar value when executing CGI scripts. Can be provided more than once. .\" don't document the "spawn " form because it probably won't .\" be kept. .It Ic fastcgi Oo Ic tcp Oc Pa socket Oo Cm port Ar port Oc Enable .Sx FastCGI instead of serving files. The .Pa socket can either be a UNIX-domain socket or a TCP socket. If the FastCGI application is listening on a UNIX domain socket, .Pa socket is a local path name within the .Xr chroot 2 root directory of .Nm . Otherwise, the .Ic tcp keyword must be provided and .Pa socket is interpreted as a hostname or an IP address. .Ar port can be either a port number or the name of a service enclosed in double quotes. If not specified defaults to 9000. .It Ic index Ar string Set the directory index file. If not specified, it defaults to .Pa index.gmi . .It Ic key Pa file Specify the private key to use for this server. The .Pa file should contain a PEM encoded private key. This option is mandatory. .It Ic lang Ar string Specify the language tag for the text/gemini content served. If not specified, no .Dq lang parameter will be added in the response. .It Ic location Pa path Brq ... Specify server configuration rules for a specific location. The .Pa 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 .Ic location section may include most of the server configuration rules except .Ic alias , Ic cert , Ic cgi , Ic entrypoint , Ic env , Ic key , .Ic location , Ic param No and Ic proxy . .It Ic log Ar bool Enable or disable the logging for the current server or location block. .It Ic param Ar name Cm = Ar value Set the param .Ar name to .Ar value for FastCGI. .It Ic ocsp Ar file Specify an OCSP response to be stapled during TLS handshakes with this server. The .Ar file should contain a DER-format OCSP response retrieved from an OCSP server for the .Ic cert in use. If the OCSP response in .Ar file is empty, OCSP stapling will not be used. The default is to not use OCSP stapling. .It Ic proxy Cm relay-to Ar host : Ns Ar port Relay the request to the given .Ar host . .Nm will connect to .Ar host : Ns Ar port and repeat the gemini request; the response will then be sent as-is to the connected client. Port is 1965 by default. .It Ic root Pa directory Specify the root directory for this server .Pq alas the current Dq document root . It's relative to the chroot if enabled. .It Ic require Ic client Ic ca Pa path Allow requests only from clients that provide a certificate signed by the CA certificate in .Pa path . It needs to be a PEM-encoded certificate and it's not relative to the chroot. .It Ic strip Ar number Strip .Ar number components from the beginning of the path before doing a lookup in the root directory. It's also considered for the .Ar meta parameter in the scope of a .Ic block return . .El .Sh CGI When a request for an executable file matches the .Ic cgi rule, that file will be executed and its output fed to the client. .Pp The CGI scripts are executed in the directory they reside and inherit the environment from .Nm with these additional variables set: .Bl -tag -width 24m .It Ev GATEWAY_INTERFACE .Dq CGI/1.1 .It Ev GEMINI_DOCUMENT_ROOT The root directory of the virtual host. .It Ev GEMINI_SCRIPT_FILENAME Full path to the CGI script being executed. .It Ev GEMINI_URL The full IRI of the request. .It Ev GEMINI_URL_PATH The path of the request. .It Ev 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. .It Ev PATH_TRANSLATED Present if and only if .Ev PATH_INFO is set. It represent the translation of the .Ev PATH_INFO . .Nm builds this by appending the .Ev PATH_INFO to the virtual host directory root. .It Ev QUERY_STRING The decoded query string. .It Ev REMOTE_ADDR , Ev REMOTE_HOST Textual representation of the client IP. .It Ev REQUEST_METHOD This is present only for RFC3875 (CGI) compliance. It's always set to the empty string. .It Ev SCRIPT_NAME The part of the .Ev GEMINI_URL_PATH that identifies the current CGI script. .It Ev SERVER_NAME The name of the server .It Ev SERVER_PORT The port the server is listening on. .It Ev SERVER_PROTOCOL .Dq GEMINI .It Ev SERVER_SOFTWARE The name and version of the server, i.e. .Dq gmid/1.7.3 .It Ev AUTH_TYPE The string "Certificate" if the client used a certificate, otherwise unset. .It Ev REMOTE_USER The subject of the client certificate if provided, otherwise unset. .It Ev TLS_CLIENT_ISSUER The is the issuer of the client certificate if provided, otherwise unset. .It Ev TLS_CLIENT_HASH The hash of the client certificate if provided, otherwise unset. The format is .Dq ALGO:HASH . .It Ev TLS_VERSION The TLS version negotiated with the peer. .It Ev TLS_CIPHER The cipher suite negotiated with the peer. .It Ev TLS_CIPHER_STRENGTH The strength in bits for the symmetric cipher that is being used with the peer. .It Ev TLS_CLIENT_NOT_AFTER The time corresponding to the end of the validity period of the peer certificate in the ISO 8601 format .Pq e.g. Dq 2021-02-07T20:17:41Z . .It Ev TLS_CLIENT_NOT_BEFORE The time corresponding to the start of the validity period of the peer certificate in the ISO 8601 format. .El .Sh FastCGI .Nm optionally supports FastCGI. A .Ic fastcgi rule must be present in a server or location block. Then, all requests matching that server or location will be handled via the specified FastCGI backend. .Pp By default the following variables .Pq parameters are sent, and carry the same semantics as with CGI. More parameters can be added with the .Ic param option. .Pp .Bl -bullet -compact .It GATEWAY_INTERFACE .It GEMINI_URL_PATH .It QUERY_STRING .It REMOTE_ADDR .It REMOTE_HOST .It REQUEST_METHOD .It SERVER_NAME .It SERVER_PROTOCOL .It SERVER_SOFTWARE .It AUTH_TYPE .It REMOTE_USER .It TLS_CLIENT_ISSUER .It TLS_CLIENT_HASH .It TLS_VERSION .It TLS_CIPHER .It TLS_CIPHER_STRENGTH .It TLS_CLIENT_NOT_BEFORE .It TLS_CLIENT_NOT_AFTER .El .Sh MIME To auto-detect the MIME type of the response .Nm looks at the file extension and consults its internal table. By default the following mappings are loaded, but they can be overridden or extended using the .Ic map configuration option. If no MIME is found, the value of .Ic default type matching the file .Ic location will be used, which is .Dq application/octet-stream by default. .Pp .Bl -tag -offset indent -width 14m -compact .It diff text/x-patch .It gemini, gmi text/gemini .It gif image/gif .It jpeg image/jpeg .It jpg image/jpeg .It markdown, md text/markdown .It patch text/x-patch .It pdf application/pdf .It png image/png .It svg image/svg+xml .It txt text/plain .It xml text/xml .El .Sh LOGGING Messages and requests are logged by .Xr syslog 3 using the .Dv DAEMON facility or printed on .Em stderr . .Pp Requests are logged with the .Dv NOTICE severity. Each request log entry has the following fields, separated by whitespace: .Pp .Bl -bullet -compact .It Client IP address and the source port number, separated by a colon .It .Sy GET keyword .It Request URL .It Response status .It Response meta .El .Sh EXAMPLES Serve the current directory .Bd -literal -offset indent $ gmid . .Ed .Pp To serve the directory .Pa docs and enable CGI scripts inside .Pa docs/cgi .Bd -literal -offset indent $ mkdir docs/cgi $ cat < docs/cgi/hello #!/bin/sh printf "20 text/plain\er\en" echo "hello world" EOF $ chmod +x docs/cgi/hello $ gmid -x '/cgi/*' docs .Ed .Pp An X.509 certificate must be provided to run .Nm using a configuration file. First, the RSA certificate is created using a wildcard common name: .Bd -literal -offset indent # openssl genrsa \-out /etc/ssl/private/example.com.key 4096 # openssl req \-new \-x509 \e \-key /etc/ssl/private/example.com.key \e \-out /etc/ssl/example.com.crt \e \-days 36500 \-nodes \e \-subj "/CN=example.com" # chmod 600 /etc/ssl/example.com.crt # chmod 600 /etc/ssl/private/example.com.key .Ed .Pp In the example above, a certificate is valid for one hundred years from the date it was created, which is normal for TOFU. .Pp The following is an example of a possible configuration for a site that enables only TLSv1.3, adds a mime type for the file extension .Qq rtf and defines two virtual host: .Bd -literal -offset indent ipv6 on # enable ipv6 protocols "tlsv1.3" map "application/rtf" to-ext "rtf" server "example.com" { cert "/etc/ssl/example.com.crt" key "/etc/ssl/private/example.com.key" root "/var/gemini/example.com" } server "it.example.com" { cert "/etc/ssl/example.com.crt" key "/etc/ssl/private/example.com.key" root "/var/gemini/it.example.com" # enable cgi scripts inside "cgi-bin" cgi "/cgi-bin/*" # set the language for text/gemini files lang "it" } .Ed .Pp Yet another example, showing how to enable a .Ic chroot and use .Ic location rule .Bd -literal -offset indent chroot "/var/gemini" user "_gmid" server "example.com" { cert "/path/to/cert.pem" # absolute path key "/path/to/key.pem" # also absolute root "/example.com" # relative to the chroot location "/static/*" { # load the following rules only for # requests that matches "/static/*" auto index on index "index.gemini" } } .Ed .Sh ACKNOWLEDGEMENTS .Nm uses the .Dq Flexible and Economical UTF-8 decoder written by .An Bjoern Hoehrmann . .Sh AUTHORS .An -nosplit The .Nm program was written by .An Omar Polo Aq Mt op@omarpolo.com . .Sh CAVEATS .Bl -bullet .It All the root directories are opened during the daemon startup; if a root directory is deleted and then re-created, .Nm won't be able to serve files inside that directory until a restart. This restriction only applies to the root directories and not their content. .It a %2F sequence is indistinguishable from a literal slash: this is not RFC3986-compliant. .It a %00 sequence is treated as invalid character and thus rejected. .El