compat | ||
contrib | ||
have | ||
regress | ||
site | ||
.cirrus.yml | ||
.dockerignore | ||
.gitignore | ||
ChangeLog | ||
config.c | ||
configure | ||
configure.local.example | ||
crypto.c | ||
dirs.c | ||
fcgi.c | ||
ge.c | ||
gemexp.1 | ||
gg.1 | ||
gg.c | ||
gmid.8 | ||
gmid.c | ||
gmid.conf.5 | ||
gmid.h | ||
iri.c | ||
iri.h | ||
LICENSE | ||
log.c | ||
log.h | ||
logger.c | ||
Makefile | ||
mime.c | ||
parse.y | ||
proc.c | ||
proc.h | ||
proxy.c | ||
puny.c | ||
README.md | ||
sandbox.c | ||
server.c | ||
titan.1 | ||
titan.c | ||
utf8.c | ||
utils.c |
gmid
Warning
The
master
branch is WIP: it's what gmid 2.0 will be, with breaking changes et al. Please use the latest release from the 1.8 branch for a stable and documented experience, thank you.
gmid is a full-featured Gemini server written with security in mind. It can serve static files, has optional FastCGI and proxying support, and a rich configuration syntax.
A few helper programs are shipped as part of gmid:
-
gg
is a simple command-line Gemini client. -
gemexp
is a stripped-down config-less version of gmid to quickly serve a directory from the command line. -
titan
is a command-line titan client.
Internationalisation (IRIs, UNICODE, punycode, all that stuff)
Even thought the current Gemini specification doesn't mention anything in this regard, I do think these are important things and so I tried to implement them in the most user-friendly way I could think of.
For starters, gmid has full support for IRI (RFC3987 — Internationalized Resource Identifiers). IRIs are a superset of URIs, so there aren't incompatibilities with URI-only clients.
There is full support also for punycode. In theory, the user doesn't
even need to know that punycode is a thing. The hostname in the
configuration file can (and must be) in the decoded form (e.g. naïve
and not xn--nave-6pa
), gmid will do the rest.
The only missing piece is UNICODE normalisation of the IRI path: gmid doesn't do that (yet).
Configuration
gmid has a rich configuration file, heavily inspired by OpenBSD' httpd(8), with every detail carefully documented in the manpage. Here's a minimal example of a config file:
server "example.com" {
listen on * port 1965
cert "/path/to/cert.pem"
key "/path/to/key.pem"
root "/var/gemini/example.com"
}
and a slightly more complex one
cert_root = "/path/to/keys"
server "example.com" {
listen on * port 1965
alias "foobar.com"
cert $cert_root "/example.com.crt"
key $cert_root "/example.com.pem"
root "/var/gemini/example.com"
# lang for text/gemini files
lang "en"
# only for locations that matches /files/*
location "/files/*" {
# generate directory listings
auto index on
}
location "/repo/*" {
# change the index file name
index "README.gmi"
lang "it"
}
}
Building
gmid depends on libevent2, OpenSSL/LibreSSL and libtls (provided either by LibreSSL or libretls). At build time, yacc (or GNU bison) is also needed.
The build is as simple as
$ ./configure
$ make
If the configure scripts fails to pick up something, please open an issue or notify me via email.
To install execute:
# make install
Please keep in mind that the master branch, from time to time, may be accidentally broken on some platforms. gmid is developed primarily on OpenBSD/amd64 and commits on the master branch don't get always tested in other OSes. Before tagging a release however, a comprehensive testing on various platform is done to ensure that everything is working as intended.
Testing
Execute
$ make regress
to start the suite. Keep in mind that the regression tests needs to
create a few file inside the regress
directory and bind the 10965
port.
Contributing
Any form of contribution is welcome, not only patches or bug reports.
If you have a sample configuration for some specific use-case, a
script or anything that could be useful to others, consider adding it
to the contrib
directory.
Architecture/Security considerations
The internal architecture was revisited for the 2.0 release. For previous releases, please refer to previous revision of this file.
gmid has a privsep design, where the operations done by the daemon are splitted into multiple processes:
-
main: the main process is the only one that keeps the original privileges. It opens the TLS certificates on the behalf of the
server
andcrypto
processes and reloads the configuration uponSIGHUP
. -
logger: logs the requests.
-
server: listen on the binded ports and serves the request. This also include speaking FastCGI and proxying requests.
-
crypto: (used only on OpenBSD at the time of writing.) Holds the TLS private keys to avoid a compromised
server
process to disclose them.