2021-01-11 13:51:25 +01:00
|
|
|
# gmid
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
gmid is a Gemini server written with security in mind. I initially
|
|
|
|
wrote it to serve static files, but it has grown into a featureful
|
|
|
|
server that can be used from either the command line to serve local
|
|
|
|
directories
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
gmid docs # serve the directory docs over gemini
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
or as a traditional daemon
|
2021-01-25 15:52:19 +01:00
|
|
|
|
|
|
|
gmid -c /etc/gmid.conf
|
|
|
|
|
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-01-13 20:06:51 +01:00
|
|
|
- IRI support (RFC3987)
|
2021-01-27 15:42:40 +01:00
|
|
|
- punycode support
|
2021-01-30 12:49:48 +01:00
|
|
|
- dual stack (IPv4 and IPv6)
|
|
|
|
- automatic certificate generation for config-less mode
|
2021-01-11 13:51:25 +01:00
|
|
|
- CGI scripts
|
|
|
|
- (very) low memory footprint
|
|
|
|
- small codebase, easily hackable
|
|
|
|
- virtual hosts
|
2021-01-27 15:42:40 +01:00
|
|
|
- per-location rules
|
|
|
|
- optional directory listings
|
|
|
|
- configurable mime types
|
2021-01-17 10:42:10 +01:00
|
|
|
- sandboxed by default on OpenBSD, Linux and FreeBSD
|
2021-01-25 11:36:21 +01:00
|
|
|
- chroot support
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2020-10-03 17:49:09 +02:00
|
|
|
|
2021-01-11 13:51:25 +01:00
|
|
|
## Drawbacks
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-11 13:51:25 +01:00
|
|
|
- not suited for very busy hosts. If you receive an high number of
|
|
|
|
connection per-second you'd probably want to run multiple gmid
|
|
|
|
instances behind relayd/haproxy or a different server.
|
2021-01-11 13:08:50 +01: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-01-11 13:51:25 +01:00
|
|
|
## Building
|
2020-10-02 19:39:00 +02:00
|
|
|
|
2021-01-27 11:52:37 +01:00
|
|
|
gmid depends on a POSIX libc, OpenSSL/LibreSSL and libtls (provided
|
|
|
|
either by LibreSSL or libretls). At build time, flex and yacc (or GNU
|
|
|
|
bison) are 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-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-01-30 12:49:48 +01:00
|
|
|
### Docker
|
|
|
|
|
|
|
|
If you have trouble installing LibreSSL or libretls, you can use
|
|
|
|
Docker to build a `gmid` image with:
|
2021-01-19 00:15:45 +01:00
|
|
|
|
|
|
|
docker build -t gmid .
|
|
|
|
|
|
|
|
and then run it with something along the lines of
|
|
|
|
|
|
|
|
docker run --rm -it -p 1965:1965 \
|
2021-01-25 15:55:03 +01:00
|
|
|
-v /path/to/gmid.conf:...:ro \
|
2021-01-19 00:15:45 +01:00
|
|
|
-v /path/to/docs:/var/gemini \
|
2021-01-25 15:55:03 +01:00
|
|
|
gmid -c .../gmid.conf
|
2021-01-19 00:15:45 +01:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
(ellipses used for brevity)
|
2021-01-19 00:15:45 +01:00
|
|
|
|
2021-01-22 18:28:39 +01:00
|
|
|
### Local libretls
|
2021-01-21 14:12:35 +01:00
|
|
|
|
|
|
|
This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
|
|
|
|
your distribution of choice or use docker instead.
|
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
However, it's possible to statically-link `gmid` to locally-installed
|
|
|
|
libretls quite easily. (It's how I test gmid on Fedora, for instance)
|
2021-01-21 14:12:35 +01:00
|
|
|
|
2021-01-21 14:14:55 +01:00
|
|
|
Let's say you have compiled and installed libretls in `$LIBRETLS`,
|
2021-01-21 14:12:35 +01:00
|
|
|
then you can build `gmid` with
|
|
|
|
|
2021-01-21 14:14:55 +01:00
|
|
|
./configure CFLAGS="-I$LIBRETLS/include" \
|
2021-01-23 13:22:09 +01:00
|
|
|
LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread"
|
2021-01-21 14:12:35 +01:00
|
|
|
make
|
|
|
|
|
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
|
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
to start the suite. Keep in mind that the regression tests will
|
|
|
|
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
|
|
|
|
|
|
|
|
gmid is composed by two processes: a listener and an executor. The
|
|
|
|
listener process is the only one that needs internet access and is
|
|
|
|
sandboxed. When a CGI script needs to be executed, the executor
|
|
|
|
(outside of the sandbox) sets up a pipe and gives one end to the
|
|
|
|
listener, while the other is bound to the CGI script standard output.
|
2021-01-27 11:52:11 +01:00
|
|
|
This way, is still possible to execute CGI scripts without
|
2021-01-30 12:49:48 +01:00
|
|
|
restrictions even in the presence of a sandboxed network process.
|
2021-01-16 20:41:34 +01:00
|
|
|
|
2021-01-30 12:49:48 +01:00
|
|
|
On OpenBSD, the listener runs with the `stdio recvfd rpath inet`
|
|
|
|
pledges, while the executor has `stdio sendfd proc exec`; both have
|
|
|
|
unveiled only the served directories.
|
2021-01-16 20:41:34 +01:00
|
|
|
|
2021-01-17 10:42:10 +01:00
|
|
|
On FreeBSD, the executor process is 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
|
|
|
|
on the BPF program.
|
2021-01-17 10:42:10 +01:00
|
|
|
|
|
|
|
In any case, you are invited to run gmid inside some sort of
|
2021-01-25 11:36:21 +01:00
|
|
|
container/jail/chroot.
|