1 twind
2 =====
3 
4 twind is a simple daemon serving static files over the gemini protocol.  It is
5 intended to have as few knobs as possible and has no support for a
6 configuration file.  twind is named after the latin word for gemini - twins.
7 
8 twind is known to run on OpenBSD, FreeBSD and Linux and currently supports
9 
10 * Serving static gemini files
11 * Virtual hosts
12 * MIME handling
13 * IPv4 and IPv6 support
14 
15 It doesn't support CGI handling and probably never will.  There are more
16 advanced gemini servers out there if you look for fancy stuff.
17 
18 Installation
19 ------------
20 
21 twind is written in plain C and you need to have the following software
22 installed:
23 
24 * A C compiler (tested with clang >= 11 and GCC >= 9)
25 * LibreSSL or OpenSSL
26 * POSIX compatible libc with pthreads support
27 * make (both BSD and GNU make will work)
28 
29 twind needs a dedicated user called '_twind' and directory to run.  The
30 Makefile contains a command to create the user.  Note that you shall not change
31 the user's name and the directory twind needs!  By default, the user ID for
32 _twind is set to 4000.  If you need another user ID, change the UID variable
33 in the Makefile.
34 
35 $ make
36 # make install
37 # make user
38 
39 TLS certificates
40 ----------------
41 
42 twind expects to find a X509 certificate and a corresponding private key
43 under the following locations (which cannot be changed):
44 
45 * /etc/twind/twind.cert.pem
46 * /etc/twind/twind.key.pem
47 
48 Either copy your existing keys to these locations or generate a new key and
49 certificate by using the Makefile.  Note that the command overwrites any existing
50 key without warning!  To generate both key and certificate use the following
51 command and provide the hostname via the HN variable.  If you don't provide the
52 hostname the command will fail!
53 
54 # make setuptls HN=example.com
55 
56 Usage
57 -----
58 
59 twind has support for virtual hosts.  If your gemini server is called
60 example.com you have to create a dedicated sub directory under /var/twind:
61 
62 # cd /var/twind
63 # mkdir example.com
64 # <copy files into the example.com directory>
65 
66 In case your server is also reachable via gemini.example.com and you want to
67 serve the same content as on example.com you can create a symlink.  In case you
68 want to serve different content, you have to create a dedicated sub directory.
69 
70 twind needs root permissions to start and will drop its privileges as soon as
71 possible.  It will also chroot to /var/twind.
72 
73 # twind
74 
75 For debugging purposes, you can start twind with -df option so that debugging
76 and running in the foreground is enabled.
77 
78 Contact
79 -------
80 
81 Please send feedback, patches by email to git()xosc.org.  Send git formatted
82 patches, see https://git-send-email.io/ for more information.