gmid/README.md

129 lines
3.7 KiB
Markdown
Raw Normal View History

2021-01-11 13:51:25 +01:00
# gmid
2020-10-02 19:39:00 +02:00
2021-01-11 13:51:25 +01:00
> dead simple, zero configuration Gemini server
2020-10-02 19:39:00 +02:00
gmid is a simple and minimal Gemini server. It can run without
configuration, so it's well suited for local development, but at the
same time has a configuration file flexible enough to meet the
requirements of most capsules.
2020-10-02 19:39:00 +02:00
2021-01-25 15:52:19 +01:00
It was initially written to serve static files, but can also
optionally execute CGI scripts. It was also written with security in
2021-01-17 10:42:10 +01:00
mind: on Linux, FreeBSD and OpenBSD is sandboxed via `seccomp(2)`,
`capsicum(4)`and `pledge(2)`+`unveil(2)` respectively.
2020-10-02 19:39:00 +02:00
2021-01-25 15:52:19 +01:00
gmid can be used from the command line to serve local directories
# serve the directory docs
gmid docs
2021-01-25 15:52:57 +01:00
or you can pass a configuration file and have access to all the
features
2021-01-25 15:52:19 +01:00
gmid -c /etc/gmid.conf
Please consult the [manpage](gmid.1) for more information.
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-13 20:06:51 +01:00
- IRI support (RFC3987)
2021-01-11 13:51:25 +01:00
- dual stack: can serve over both IPv4 and IPv6
- CGI scripts
- (very) low memory footprint
- small codebase, easily hackable
- virtual hosts
2021-01-25 15:52:19 +01:00
- rules per-location
- directory listings
- mime types configurable
- index file configurable
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: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
The build is as simple as
2020-10-02 19:39:00 +02:00
2021-01-11 13:51:25 +01:00
make
2020-10-02 19:39:00 +02: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.
To install execute:
make install
2021-01-19 00:15:45 +01:00
If you have trouble installing LibreSSL or libretls, as they aren't
available as package on various Linux distribution, you can use Docker
to build a `gmid` image with:
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-25 15:55:03 +01:00
ellipses for brevity.
2021-01-19 00:15:45 +01:00
2021-01-22 18:28:39 +01:00
### Local libretls
This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
your distribution of choice or use docker instead.
However, it's possible to link `gmid` to locally-installed libtls
quite easily. (It's how I test gmid on Fedora, for instance)
2021-01-21 14:14:55 +01:00
Let's say you have compiled and installed libretls in `$LIBRETLS`,
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"
make
2021-01-22 18:28:39 +01:00
### Testing
Execute
2021-01-22 18:28:39 +01:00
make regress
2021-01-22 18:54:37 +01:00
to start the suite. Keep in mind that the suite will create files
2021-01-22 18:28:39 +01:00
inside the `regress` directory and bind the 10965 port.
## 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
restrictions even in the presence of a sandbox.
On OpenBSD, the listener process runs with the `stdio recvfd rpath
2021-01-27 11:52:37 +01:00
inet` pledges, the executor has `stdio sendfd proc exec` as pledges;
both have unveiled only the served directories.
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-17 11:06:52 +01:00
On Linux, a `seccomp(2)` filter is installed to allow only certain
syscalls, see [sandbox.c](sandbox.c) for more information on the BPF
2021-01-17 10:42:10 +01:00
program.
In any case, you are invited to run gmid inside some sort of
2021-01-25 11:36:21 +01:00
container/jail/chroot.