.\" Copyright (c) 2020 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: October 2 2020$ .Dt GMIND 1 .Os .Sh NAME .Nm gmid .Nd dead simple zero configuration gemini server .Sh SYNOPSIS .Nm .Bk -words .Op Fl n .Op Fl c Ar config | .Op Fl 6fh .Op Fl C Ar cert .Op Fl d Ar root .Op Fl K Ar key .Op Fl p Ar port .Op Fl x Ar directory .Ek .Sh DESCRIPTION .Nm is a simple and minimal gemini server that can serve static files and execute CGI scripts. It can run without a configuration file with a limited set of features available. If a configuration file is given, no other flags shall be given, except for .Fl n . .Pp .Nm fully supports IRIs (Internationalized Resource Identifiers, see RFC3987). .Pp The options are as follows: .Bl -tag -width 12m .It Fl c Pa config Specifies the configuration file. .It Fl n Check that the configuration is valid, but don't start the server. .El .Pp If no configuration file is given, .Nm will look for the following option .Bl -tag -width 12m .It Fl 6 Enable IPv6. .It Fl C Pa file The certificate to use. .It Fl d Pa directory The root directory to serve. .It Fl f Stays and log in the foreground, do not daemonize the process. .It Fl h Print the usage and exit. .It Fl K Pa file The key for the certificate. .It Fl p Ar port The port to listen on, by default 1965. .It Fl x Pa directory Enable execution of CGI scripts. See the description of the .Ic cgi .Ic server option in the section .Sq Servers below to learn how .Pa directory is processed. Cannot be provided more than once. .El .Sh CONFIGURATION FILE The configuration file is divided into two sections: .Bl -tag -width xxxx .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 . .Ss Global Options .Bl -tag -width 12m .It Ic daemon Ar bool Enable or disables the daemon mode. In daemon mode .Nm will log to syslog and fork in the background. By default is off. .It Ic ipv6 Ar bool Enable or disable IPv6 support. By default is off. .It Ic port Ar portno The port to listen on. By default is 1965. .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 used. Use .Dq tlsv1.3 to enable only TLSv1.3. .It Ic mime Ar mime-type Ar file-extension Add a mapping for the given .Ar file-extension to the given .Ar mime-type . Both argument are strings. .El .Ss Servers Every virtual host is defined by a .Ic server block: .Bl -tag -width Ds .It Ic server Ar hostname Brq ... .El .Pp Followed by a block of options that is enclosed in curly brackets: .Bl -tag -width Ds .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 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 root Pa directory Specify the root directory for this server. This option is mandatory. .It Ic cgi Pa path Enable the execution of CGI scripts if .Pa path is a prefix of the user request string. An empty path "" will effectively enable the execution of any file with the executable bit set inside the root directory. .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 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. .El .Sh CGI When CGI scripts are enabled for a directory, a request for an executable file will execute it and fed its output to the client. .Pp The CGI scripts will inherit the environment from .Nm with these additional variables set: .Bl -tag -width 18m .It Ev SERVER_SOFTWARE "gmid" .It Ev SERVER_PORT "1965" .It Ev SCRIPT_NAME The (public) path to the script. .It Ev SCRIPT_EXECUTABLE The full path to the executable. .It Ev REQUEST_URI The user request (without the query parameters.) .It Ev REQUEST_RELATIVE The request relative to the script. .It Ev QUERY_STRING The query parameters. .It Ev REMOTE_HOST The remote IP address. .It Ev REMOTE_ADDR The remote IP address. .It Ev DOCUMENT_ROOT The root directory being served, the one provided with the .Ar d parameter to .Nm or the root directory of the virtual host. .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 "ALGO:HASH". .El .Pp Let's say you have a script in .Pa /cgi-bin/script and the user request is .Pa /cgi-bin/script/foo/bar?quux . Then .Ev SCRIPT_NAME will be .Pa cgi-bin/script , .Ev SCRIPT_EXECUTABLE will be .Pa $DOCUMENT_ROOT/cgi-bin/script , .Ev REQUEST_URI will be .Pa cgi-bin/script/foo/bar , .Ev REQUEST_RELATIVE will be .Pa foo/bar and .Ev QUERY_STRING will be .Ar quux . .Sh EXAMPLES To quickly getting started .Bd -literal -offset indent $ # generate a cert and a key $ openssl req -x509 -newkey rsa:4096 -keyout key.pem \\ -out cert.pem -days 365 -nodes $ mkdir docs $ cat < docs/index.gmi # Hello world test paragraph... EOF $ gmid -c cert.pem -k key.pem -d docs .Ed .Pp Now you can visit gemini://localhost/ with your preferred gemini client. .Pp To add some CGI scripts, assuming a setup similar to the previous example, you can .Bd -literal -offset indent $ mkdir docs/cgi-bin $ cat < docs/cgi-bin/hello-world #!/bin/sh printf "20 text/plain\\r\\n" echo "hello world!" EOF $ gmid -x cgi-bin .Ed .Pp Note that the argument to the .Fl x option is .Pa cgi-bin and not .Pa docs/cgi-bin , since it's relative to the document root. .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 "rtf" and defines two virtual host: .Bd -literal -offset indent ipv6 on # enable ipv6 daemon on # enable daemon mode protocols "tlsv1.3" mime "application/rtf" "rtf" server "example.com" { cert "/path/to/cert.pem" key "/path/to/key.pem" root "/var/gemini/example.com" } server "it.example.com" { cert "/path/to/cert.pem" key "/path/to/key.pem" root "/var/gemini/it.example.com" cgi "/cgi-bin" } .Ed .Sh ACKNOWLEDGEMENTS .Nm uses the .Dq Flexible and Economical UTF-8 decoder written by .An Bjoern Hoehrmann for its IRI parser. .Sh CAVEATS .Bl -bullet .It The root directories of all virtual hosts are opened during the daemon startup; this means that if a root directory gets deleted and then re-created, .Nm won't be able to serve files inside that directory until a restart. This restriction applies only to the root directories and not their content. .It a %2F sequence in the path part is indistinguishable from a literal slash: this is not RFC3986-compliant. .It a %00 sequence either in the path or in the query part is treated as invalid character and thus rejected. .El