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. If specified two or more time, dump the configuration in addition to verify it.

-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 runs in “config-less mode” (i.e. runs in the foreground to serve a directory from the shell) and looks 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.

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

To run gmid as a deamon a configuration file and a X.509 certificate must be provided. A self-signed certificate, which are commonly used in the Geminispace, can be generated using for e.g. openssl(1):

    # openssl req -x509 -newkey rsa:4096 -nodes \
    	-keyout /etc/ssl/private/example.com.key \
    	-out /etc/ssl/example.com.pem \
    	-days 365 -subj "/CN=example.com"
    # chmod 600 /etc/ssl/example.com.crt
    # chmod 600 /etc/ssl/private/example.com.key

Then gmid can be started with

    # gmid -c /etc/gmid.conf

SEE ALSO
gmid.conf(5)

ACKNOWLEDGEMENTS
gmid uses the “Flexible and Economical” UTF-8 decoder written by Bjoern Hoehrmann.

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