3 b9220ca4 2021-01-11 op > dead simple, zero configuration Gemini server
5 881a9dd9 2021-01-16 op gmid is a simple and minimal Gemini server. It can run without
6 881a9dd9 2021-01-16 op configuration, so it's well suited for local development, but at the
7 881a9dd9 2021-01-16 op same time has a configuration file flexible enough to meet the
8 881a9dd9 2021-01-16 op requirements of most capsules.
10 2f09adb0 2021-01-25 op It was initially written to serve static files, but can also
11 881a9dd9 2021-01-16 op optionally execute CGI scripts. It was also written with security in
12 ea58dab1 2021-01-17 op mind: on Linux, FreeBSD and OpenBSD is sandboxed via `seccomp(2)`,
13 ea58dab1 2021-01-17 op `capsicum(4)`and `pledge(2)`+`unveil(2)` respectively.
15 2f09adb0 2021-01-25 op gmid can be used from the command line to serve local directories
17 2f09adb0 2021-01-25 op # serve the directory docs
20 0a0e6ba7 2021-01-25 op or you can pass a configuration file and have access to all the
23 2f09adb0 2021-01-25 op gmid -c /etc/gmid.conf
25 2f09adb0 2021-01-25 op Please consult the [manpage](gmid.1) for more information.
30 4d2ec6d7 2021-01-13 op - IRI support (RFC3987)
31 b9220ca4 2021-01-11 op - dual stack: can serve over both IPv4 and IPv6
33 b9220ca4 2021-01-11 op - (very) low memory footprint
34 b9220ca4 2021-01-11 op - small codebase, easily hackable
35 b9220ca4 2021-01-11 op - virtual hosts
36 2f09adb0 2021-01-25 op - rules per-location
37 2f09adb0 2021-01-25 op - directory listings
38 2f09adb0 2021-01-25 op - mime types configurable
39 2f09adb0 2021-01-25 op - index file configurable
40 ea58dab1 2021-01-17 op - sandboxed by default on OpenBSD, Linux and FreeBSD
41 0b00962d 2021-01-25 op - chroot support
46 b9220ca4 2021-01-11 op - not suited for very busy hosts. If you receive an high number of
47 b9220ca4 2021-01-11 op connection per-second you'd probably want to run multiple gmid
48 b9220ca4 2021-01-11 op instances behind relayd/haproxy or a different server.
52 42650ade 2021-01-27 op gmid depends on a POSIX libc, OpenSSL/LibreSSL and libtls (provided
53 42650ade 2021-01-27 op either by LibreSSL or libretls). At build time, flex and yacc (or GNU
54 42650ade 2021-01-27 op bison) are also needed.
56 771d8f28 2021-01-17 op The build is as simple as
60 8f0da580 2021-01-21 op If the configure scripts fails to pick up something, please open an
61 f980545b 2021-01-21 op issue or notify me via email.
63 771d8f28 2021-01-17 op To install execute:
67 17b09e3c 2021-01-18 op If you have trouble installing LibreSSL or libretls, as they aren't
68 17b09e3c 2021-01-18 op available as package on various Linux distribution, you can use Docker
69 17b09e3c 2021-01-18 op to build a `gmid` image with:
71 17b09e3c 2021-01-18 op docker build -t gmid .
73 17b09e3c 2021-01-18 op and then run it with something along the lines of
75 17b09e3c 2021-01-18 op docker run --rm -it -p 1965:1965 \
76 6c117838 2021-01-25 op -v /path/to/gmid.conf:...:ro \
77 17b09e3c 2021-01-18 op -v /path/to/docs:/var/gemini \
78 6c117838 2021-01-25 op gmid -c .../gmid.conf
80 6c117838 2021-01-25 op ellipses for brevity.
82 dd8cc7d3 2021-01-22 op ### Local libretls
84 8f0da580 2021-01-21 op This is **NOT** recommended, please try to port LibreSSL/LibreTLS to
85 8f0da580 2021-01-21 op your distribution of choice or use docker instead.
87 8f0da580 2021-01-21 op However, it's possible to link `gmid` to locally-installed libtls
88 8f0da580 2021-01-21 op quite easily. (It's how I test gmid on Fedora, for instance)
90 04397b32 2021-01-21 op Let's say you have compiled and installed libretls in `$LIBRETLS`,
91 8f0da580 2021-01-21 op then you can build `gmid` with
93 04397b32 2021-01-21 op ./configure CFLAGS="-I$LIBRETLS/include" \
94 45b4aa6e 2021-01-23 op LDFLAGS="$LIBRETLS/lib/libtls.a -lssl -lcrypto -lpthread"
103 7f740a14 2021-01-22 op to start the suite. Keep in mind that the suite will create files
104 dd8cc7d3 2021-01-22 op inside the `regress` directory and bind the 10965 port.
107 881a9dd9 2021-01-16 op ## Architecture/Security considerations
109 881a9dd9 2021-01-16 op gmid is composed by two processes: a listener and an executor. The
110 881a9dd9 2021-01-16 op listener process is the only one that needs internet access and is
111 881a9dd9 2021-01-16 op sandboxed. When a CGI script needs to be executed, the executor
112 881a9dd9 2021-01-16 op (outside of the sandbox) sets up a pipe and gives one end to the
113 881a9dd9 2021-01-16 op listener, while the other is bound to the CGI script standard output.
114 909ea500 2021-01-27 op This way, is still possible to execute CGI scripts without
115 909ea500 2021-01-27 op restrictions even in the presence of a sandbox.
117 881a9dd9 2021-01-16 op On OpenBSD, the listener process runs with the `stdio recvfd rpath
118 42650ade 2021-01-27 op inet` pledges, the executor has `stdio sendfd proc exec` as pledges;
119 42650ade 2021-01-27 op both have unveiled only the served directories.
121 ea58dab1 2021-01-17 op On FreeBSD, the executor process is sandboxed with `capsicum(4)`.
123 76fd55f4 2021-01-17 op On Linux, a `seccomp(2)` filter is installed to allow only certain
124 76fd55f4 2021-01-17 op syscalls, see [sandbox.c](sandbox.c) for more information on the BPF
127 ea58dab1 2021-01-17 op In any case, you are invited to run gmid inside some sort of
128 0b00962d 2021-01-25 op container/jail/chroot.
