.cirrus.ymlcommits | blame
.dockerignorecommits | blame
.gitignorecommits | blame
ChangeLogcommits | blame
LICENSEcommits | blame
Makefilecommits | blame
README.mdcommits | blame
config.ccommits | blame
configure*commits | blame
configure.local.examplecommits | blame
crypto.ccommits | blame
dirs.ccommits | blame
fcgi.ccommits | blame
ge.1commits | blame
ge.ccommits | blame
gg.1commits | blame
gg.ccommits | blame
gmid.8commits | blame
gmid.ccommits | blame
gmid.conf.5commits | blame
gmid.hcommits | blame
iri.ccommits | blame
iri.hcommits | blame
log.ccommits | blame
log.hcommits | blame
logger.ccommits | blame
mime.ccommits | blame
parse.ycommits | blame
proc.ccommits | blame
proc.hcommits | blame
proxy.ccommits | blame
puny.ccommits | blame
sandbox.ccommits | blame
server.ccommits | blame
titan.ccommits | blame
utf8.ccommits | blame
utils.ccommits | blame

# 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.

gg is a simple command-line Gemini client, and ge a stripped-down
config-less gmid version used to quickly serve a directory locally
over Gemini.

## 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)][httpd], with every detail carefully documented in the
manpage.  Here's a minimal example of a config file:

server "" {
	listen on * port 1965
	cert "/path/to/cert.pem"
	key  "/path/to/key.pem"
	root "/var/gemini/"

and a slightly more complex one

cert_root = "/path/to/keys"

server "" {
	listen on * port 1965

	alias ""

	cert $cert_root "/"
	key  $cert_root "/"
	root "/var/gemini/"

	# 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


	$ 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

## 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` and `crypto` processes and reloads the configuration upon

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