2021-01-11 13:51:25 +01:00
|
|
|
# gmid
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-02-08 19:47:36 +01:00
|
|
|
gmid is a fast Gemini server written with security in mind. I
|
|
|
|
initially wrote it to serve static files, but it has grown into a
|
2021-02-08 19:54:34 +01:00
|
|
|
featureful server.
|
2021-01-25 15:52:19 +01:00
|
|
|
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-11 13:51:25 +01:00
|
|
|
## Features
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
(random order)
|
|
|
|
|
2021-04-29 21:46:51 +02:00
|
|
|
- sandboxed by default on OpenBSD, Linux and FreeBSD
|
2021-02-08 19:54:34 +01:00
|
|
|
- reconfiguration: reload the running configuration without
|
|
|
|
interruption
|
2021-02-23 14:22:29 +01:00
|
|
|
- automatic redirect/error pages (see `block return`)
|
2021-01-13 20:06:51 +01:00
|
|
|
- IRI support (RFC3987)
|
2021-01-30 12:49:48 +01:00
|
|
|
- automatic certificate generation for config-less mode
|
2021-12-29 21:53:22 +01:00
|
|
|
- reverse proxying
|
2021-06-11 18:11:58 +02:00
|
|
|
- CGI and FastCGI support
|
2021-04-29 21:46:51 +02:00
|
|
|
- virtual hosts
|
|
|
|
- location rules
|
2021-02-08 19:47:36 +01:00
|
|
|
- event-based asynchronous I/O model
|
2021-04-29 21:46:51 +02:00
|
|
|
- low memory footprint
|
2021-01-11 13:51:25 +01:00
|
|
|
- small codebase, easily hackable
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2020-10-03 17:49:09 +02:00
|
|
|
|
2021-01-27 15:42:40 +01:00
|
|
|
## Internationalisation (IRIs, UNICODE, punycode, all that stuff)
|
|
|
|
|
|
|
|
Even thought the current Gemini specification doesn't mention anything
|
2021-01-30 12:49:48 +01:00
|
|
|
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.
|
2021-01-27 15:42:40 +01:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
For starters, gmid has full support for IRI (RFC3987 —
|
2021-01-29 18:07:26 +01:00
|
|
|
Internationalized Resource Identifiers). IRIs are a superset of URIs,
|
2021-01-27 15:42:40 +01:00
|
|
|
so there aren't incompatibilities with URI-only clients.
|
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
There is full support also for punycode. In theory, the user doesn't
|
2021-01-27 15:42:40 +01:00
|
|
|
even need to know that punycode is a thing. The hostname in the
|
2021-01-30 12:49:48 +01:00
|
|
|
configuration file can (and must be) in the decoded form (e.g. `naïve`
|
|
|
|
and not `xn--nave-6pa`), gmid will do the rest.
|
2021-01-27 15:42:40 +01:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
The only missing piece is UNICODE normalisation of the IRI path: gmid
|
|
|
|
doesn't do that (yet).
|
2021-01-27 15:42:40 +01:00
|
|
|
|
|
|
|
|
2021-02-06 20:05:40 +01:00
|
|
|
## Configuration
|
|
|
|
|
|
|
|
gmid has a rich configuration file, heavily inspired by OpenBSD'
|
2021-04-29 21:46:51 +02:00
|
|
|
httpd, with every detail carefully documented in the manpage. Here's
|
|
|
|
a minimal example of a config file:
|
|
|
|
|
|
|
|
```conf
|
|
|
|
server "example.com" {
|
|
|
|
cert "/path/to/cert.pem"
|
|
|
|
key "/path/to/key.pem"
|
|
|
|
root "/var/gemini/example.com"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2021-07-06 13:41:24 +02:00
|
|
|
and a slightly more complex one
|
2021-02-06 20:05:40 +01:00
|
|
|
|
|
|
|
```conf
|
|
|
|
ipv6 on # enable ipv6
|
|
|
|
|
2021-07-06 13:41:24 +02:00
|
|
|
# define a macro
|
|
|
|
cert_root = "/path/to/keys"
|
|
|
|
|
2021-02-06 20:05:40 +01:00
|
|
|
server "example.com" {
|
2021-04-29 21:46:51 +02:00
|
|
|
alias "foobar.com"
|
|
|
|
|
2021-07-06 13:41:24 +02:00
|
|
|
cert $cert_root "/example.com.crt"
|
|
|
|
key $cert_root "/example.com.pem"
|
2021-04-29 21:46:51 +02:00
|
|
|
root "/var/gemini/example.com"
|
|
|
|
|
|
|
|
# lang for text/gemini files
|
2021-07-06 13:41:24 +02:00
|
|
|
lang "en"
|
2021-04-29 21:46:51 +02:00
|
|
|
|
|
|
|
# execute CGI scripts in /cgi/
|
2021-04-29 21:50:25 +02:00
|
|
|
cgi "/cgi/*"
|
2021-04-29 21:46:51 +02:00
|
|
|
|
|
|
|
# only for locations that matches /files/*
|
|
|
|
location "/files/*" {
|
|
|
|
# generate directory listings
|
|
|
|
auto index on
|
|
|
|
}
|
|
|
|
|
|
|
|
location "/repo/*" {
|
|
|
|
# change the index file name
|
|
|
|
index "README.gmi"
|
2021-07-06 13:41:24 +02:00
|
|
|
lang "it"
|
2021-04-29 21:46:51 +02:00
|
|
|
}
|
2021-02-06 20:05:40 +01:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
2021-01-11 13:51:25 +01:00
|
|
|
## Building
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-02-08 19:47:36 +01:00
|
|
|
gmid depends on a POSIX libc, libevent2, OpenSSL/LibreSSL and libtls
|
2021-06-16 16:43:16 +02:00
|
|
|
(provided either by LibreSSL or libretls). At build time, yacc (or
|
|
|
|
GNU bison) is also needed.
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-17 13:12:37 +01:00
|
|
|
The build is as simple as
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
./configure
|
2021-01-11 13:51:25 +01:00
|
|
|
make
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-03-29 12:13:17 +02:00
|
|
|
or `make static` to build a statically-linked executable.
|
|
|
|
|
2021-01-21 14:12:35 +01:00
|
|
|
If the configure scripts fails to pick up something, please open an
|
2021-01-21 14:16:14 +01:00
|
|
|
issue or notify me via email.
|
2021-01-21 14:12:35 +01:00
|
|
|
|
2021-01-17 13:12:37 +01:00
|
|
|
To install execute:
|
|
|
|
|
|
|
|
make install
|
|
|
|
|
2021-04-25 14:01:34 +02:00
|
|
|
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
|
2021-04-27 09:14:00 +02:00
|
|
|
testing on various platform is done to ensure that everything is
|
|
|
|
working as intended.
|
2021-04-25 14:01:34 +02:00
|
|
|
|
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
### Docker
|
|
|
|
|
2021-07-11 22:58:57 +02:00
|
|
|
If you have trouble installing LibreSSL or libretls, in `contrib`
|
|
|
|
there's a sample Dockerfile. See [the contrib page][contrib-page] for
|
|
|
|
more information.
|
2021-01-19 00:15:45 +01:00
|
|
|
|
2021-07-11 22:58:57 +02:00
|
|
|
[contrib-page]: https://gmid.omarpolo.com/contrib.html#dockerfile
|
2021-01-19 00:15:45 +01:00
|
|
|
|
2021-01-22 18:28:39 +01:00
|
|
|
### Testing
|
|
|
|
|
2021-01-23 18:10:00 +01:00
|
|
|
Execute
|
2021-01-22 18:28:39 +01:00
|
|
|
|
|
|
|
make regress
|
|
|
|
|
2022-02-18 10:09:23 +01:00
|
|
|
to start the suite. Keep in mind that the regression tests needs to
|
2021-01-30 12:49:48 +01:00
|
|
|
create files inside the `regress` directory and bind the 10965 port.
|
2021-01-22 18:28:39 +01:00
|
|
|
|
|
|
|
|
2021-01-16 20:41:34 +01:00
|
|
|
## Architecture/Security considerations
|
|
|
|
|
2021-02-23 14:22:29 +01:00
|
|
|
gmid is composed by four processes: the parent process, the logger,
|
|
|
|
the listener and the executor. The parent process is the only one
|
|
|
|
that doesn't drop privileges, but all it does is to wait for a SIGHUP
|
|
|
|
to reload the configuration and spawn a new generation of children
|
2021-07-29 06:13:43 +02:00
|
|
|
process. The logger process gathers the logs and prints 'em to
|
2021-02-23 14:22:29 +01:00
|
|
|
stderr or syslog (for the time being.) The listener process is the
|
|
|
|
only one that needs internet access and is sandboxed by default. The
|
2021-07-09 10:11:57 +02:00
|
|
|
executor process exists only to fork and execute CGI scripts, and
|
|
|
|
optionally to connect to FastCGI applications.
|
2021-01-16 20:41:34 +01:00
|
|
|
|
2021-10-24 18:52:39 +02:00
|
|
|
On OpenBSD the processes are all `pledge(2)`d and `unveil(2)`ed.
|
2021-01-16 20:41:34 +01:00
|
|
|
|
2021-03-20 12:08:17 +01:00
|
|
|
On FreeBSD, the listener and logger process are sandboxed with `capsicum(4)`.
|
2021-01-17 10:33:45 +01:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
On Linux, a `seccomp(2)` filter is installed in the listener to allow
|
|
|
|
only certain syscalls, see [sandbox.c](sandbox.c) for more information
|
2021-09-19 19:08:12 +02:00
|
|
|
about the BPF program. If available, landlock is used to limit the
|
|
|
|
portion of the file system gmid can access (requires linux 5.13+.)
|
2021-01-17 10:42:10 +01:00
|
|
|
|
2021-06-04 09:14:50 +02:00
|
|
|
In any case, it's advisable to run gmid inside some sort of
|
2021-01-25 11:36:21 +01:00
|
|
|
container/jail/chroot.
|