Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/omar-polo/gmid

a Gemini server
https://github.com/omar-polo/gmid

gemini gemini-protocol gemini-server libtls

Last synced: 1 day ago
JSON representation

a Gemini server

Awesome Lists containing this project

README 

        
# 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, IDN, UNICODE)



Even thought the current Gemini specification doesn't mention anything

in this regard, I think it's important to make as easy as possible to

use non-ASCII characters in domain names and URL paths.



For starters, gmid has full support for IRIs (RFC3987 —

Internationalized Resource Identifiers).  IRIs are a superset of URIs

that allow UNICODE characters, so there aren't incompatibilities with

URI-only clients.



There is full support also for IDNs (Internationalized Domain Names).

There's no need to fiddle with punycode, or even know what it is: 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



[httpd]: https://man.openbsd.org/httpd.8



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:



```conf

# /etc/gmid.conf

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



```conf

# /etc/gmid.conf

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



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

10966 ports.



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



gmid has a privsep design, where the operations done by the daemon are

split 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 handles the requests.  It also

   speaks FastCGI and do the proxying.



 - crypto: holds the TLS private keys to avoid a compromised `server`

   process to disclose them.