💾 Archived View for gmid.omarpolo.com › gmid.1.txt captured on 2021-12-17 at 13:26:06.
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
GMID(1) General Commands Manual GMID(1)
NAME
gmid simple and secure Gemini server
SYNOPSIS
gmid [-fnv] [-c config] [-D macro=value] [-P pidfile]
gmid [-6hVv] [-d certs-dir] [-H hostname] [-p port] [-x cgi] [dir]
DESCRIPTION
gmid 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.
gmid rereads the configuration file when it receives SIGHUP.
The options are as follows:
-c config Specify the configuration file.
-D macro=value Define macro to be set to value on the command line.
Overrides the definition of macro in the config file if
present.
-f Stays and logs on the foreground.
-n Check that the configuration is valid, but don't start
the server.
-P pidfile Write daemon's pid to the given location. pidfile will
also act as lock: if another process is holding a lock on
that file, gmid will refuse to start.
If no configuration file is given, gmid will look for the following
options
-6 Enable IPv6.
-d certs-path Directory where certificates for the config-less mode are
stored. By default it is $XDG_DATA_HOME/gmid, i.e.
~/.local/share/gmid.
-H hostname The hostname (localhost by default). Certificates for
the given hostname are searched inside the certs-dir
directory given with the -d option. They have the form
hostname.cert.pem and hostname.key.pem. If a certificate
or a key doesn't exist for a given hostname, they will be
generated automatically.
-h, --help Print the usage and exit.
-p port The port to listen on, by default 1965.
-V, --version Print the version and exit.
-v Verbose mode. Multiple -v options increase the
verbosity.
-x path Enable execution of CGI scripts. See the description of
the cgi option in the Servers section below to learn
how path is processed. Cannot be provided more than
once.
dir The root directory to serve. By default the current
working directory is assumed.
CONFIGURATION FILE
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.
Servers
Virtual hosts definition.
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.crt" # -> /etc/keys/foo.crt
key $certdir "/foo.pem" # -> /etc/keys/foo.pem
@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 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 may enforce this.
ipv6 bool Enable or disable IPv6 support, off by default.
map mime-type to-ext file-extension
Map mime-type to the given file-extension. Both argument
are strings.
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
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. The file should
contain a PEM encoded certificate. This option is mandatory.
cgi path
Execute CGI scripts that matches path using shell globbing rules.
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.
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. The 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. The
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 and
param.
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.
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.
CGI
When a request for an executable file matches the cgi rule, that file
will be executed and its output fed to the client.
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.7.5
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.
FastCGI
gmid optionally supports FastCGI. A 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.
By default the following variables (parameters) are sent, and carry the
same semantics as with CGI. More parameters can be added with the param
option.
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
MIME
To auto-detect the MIME type of the response gmid 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 map
configuration option. If no MIME is found, the value of default type
matching the file location will be used, which is
application/octet-stream by default.
diff text/x-patch
gemini, gmi text/gemini
gif image/gif
jpeg image/jpeg
jpg image/jpeg
markdown, md text/markdown
patch text/x-patch
pdf application/pdf
png image/png
svg image/svg+xml
txt text/plain
xml text/xml
LOGGING
Messages and requests are logged by syslog(3) using the DAEMON facility
or printed on stderr.
Requests are logged with the NOTICE severity. Each request log entry has
the following fields, separated by whitespace:
Client IP address and the source port number, separated by a colon
GET keyword
Request URL
Response status
Response meta
EXAMPLES
Serve the current directory
$ gmid .
To serve the directory docs and enable CGI scripts inside docs/cgi
$ mkdir docs/cgi
$ cat <<EOF > docs/cgi/hello
#!/bin/sh
printf "20 text/plain\r\n"
echo "hello world"
EOF
$ chmod +x docs/cgi/hello
$ gmid -x '/cgi/*' docs
An X.509 certificate must be provided to run gmid using a configuration
file. First, the RSA certificate is created using a wildcard common
name:
# openssl genrsa -out /etc/ssl/private/example.com.key 4096
# openssl req -new -x509 -key /etc/ssl/private/example.com.key \
-out /etc/ssl/example.com.crt -days 36500 -nodes \
-subj "/CN=example.com"
# chmod 600 /etc/ssl/example.com.crt
# chmod 600 /etc/ssl/private/example.com.key
In the example above, a certificate is valid for one hundred years from
the date it was created, which is normal for TOFU.
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:
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"
}
Yet another example, showing how to enable a chroot and use location rule
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"
}
}
ACKNOWLEDGEMENTS
gmid uses the Flexible and Economical UTF-8 decoder written by Bjoern
Hoehrmann.
AUTHORS
The gmid program was written by Omar Polo <op@omarpolo.com>.
CAVEATS
All the root directories are opened during the daemon startup; if a
root directory is deleted and then re-created, gmid 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.
a %2F sequence is indistinguishable from a literal slash: this is not
RFC3986-compliant.
a %00 sequence is treated as invalid character and thus rejected.
OpenBSD 7.0 July 29, 2021 OpenBSD 7.0