.cirrus.ymlcommits | blame
.dockerignorecommits | blame
.gitignorecommits | blame
ChangeLogcommits | blame
LICENSEcommits | blame
Makefilecommits | blame
README.mdcommits | blame
config.ccommits | blame
configure*commits | blame
crypto.ccommits | blame
dirs.ccommits | blame
fcgi.ccommits | blame
ge.ccommits | blame
gemexp.1commits | 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-proto.ccommits | blame
proxy.ccommits | blame
puny.ccommits | blame
sandbox.ccommits | blame
server.ccommits | blame
titan.1commits | blame
titan.ccommits | blame
utf8.ccommits | blame
utils.ccommits | blame

# gmid

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

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

and a slightly more complex one

# /etc/gmid.conf
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, LibreSSL or OpenSSL, and yacc or GNU bison.

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
earlier 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, reloads the configuration upon
   `SIGHUP` and re-opens the log files upon `SIGUSR1`.

 - logger: handles the logging with syslog and/or local files.

 - server: listens for connections and serves the request.  It also
   speaks FastCGI and do the proxying.

 - crypto: holds the TLS private keys to avoid a compromised `server`
   process to disclose them.