commit - 714685c10c68d3c1c8b990b9877fbc72b38562c1
commit + 601bc1cc3797c8afc6610478cab9004be7a2c7b0
blob - 65c8a6665134749a0ad3039c8f2279492ce3c0f9
blob + 7e02bda4f19f902b9da55b35f9c2bf1ac85040bd
--- README.md
+++ README.md
# gmid
-> dead simple, zero configuration Gemini server
+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
-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.
+ gmid docs # serve the directory docs over gemini
-It was initially written to serve static files, but can also
-optionally execute CGI scripts. It was also written with security in
-mind: on Linux, FreeBSD and OpenBSD is sandboxed via `seccomp(2)`,
-`capsicum(4)`and `pledge(2)`+`unveil(2)` respectively.
+or as a traditional daemon
-gmid can be used from the command line to serve local directories
-
- # serve the directory docs
- gmid docs
-
-or you can pass a configuration file and have access to all the
-features
-
gmid -c /etc/gmid.conf
-Please consult the [manpage](gmid.1) for more information.
-
## Features
+(random order)
+
- IRI support (RFC3987)
- punycode support
- - dual stack: can serve over both IPv4 and IPv6
- - automatic certificate generation (in config-less mode)
+ - dual stack (IPv4 and IPv6)
+ - automatic certificate generation for config-less mode
- CGI scripts
- (very) low memory footprint
- small codebase, easily hackable
## 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, so I tried to
-implement them in the most user-friendly way I could think of.
+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 --
+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 users doesn't
+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) written with proper UNICODE, gmid
-will do the rest.
+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. gmid doesn't
-do that (yet).
+The only missing piece is UNICODE normalisation of the IRI path: gmid
+doesn't do that (yet).
## Building
The build is as simple as
+ ./configure
make
If the configure scripts fails to pick up something, please open an
make install
-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
+If you have trouble installing LibreSSL or libretls, you can use
+Docker to build a `gmid` image with:
+
docker build -t gmid .
and then run it with something along the lines of
-v /path/to/docs:/var/gemini \
gmid -c .../gmid.conf
-ellipses for brevity.
+(ellipses used for brevity)
### 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)
+However, it's possible to statically-link `gmid` to locally-installed
+libretls quite easily. (It's how I test gmid on Fedora, for instance)
Let's say you have compiled and installed libretls in `$LIBRETLS`,
then you can build `gmid` with
make regress
-to start the suite. Keep in mind that the suite will create files
-inside the `regress` directory and bind the 10965 port.
+to start the suite. Keep in mind that the regression tests will
+create files inside the `regress` directory and bind the 10965 port.
## Architecture/Security considerations
(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.
This way, is still possible to execute CGI scripts without
-restrictions even in the presence of a sandbox.
+restrictions even in the presence of a sandboxed network process.
-On OpenBSD, the listener process runs with the `stdio recvfd rpath
-inet` pledges, the executor has `stdio sendfd proc exec` as pledges;
-both have unveiled only the served directories.
+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.
On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
-On Linux, a `seccomp(2)` filter is installed to allow only certain
-syscalls, see [sandbox.c](sandbox.c) for more information on the BPF
-program.
+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.
In any case, you are invited to run gmid inside some sort of
container/jail/chroot.
