1 
2 # NAME
3 
4 **gmid** - dead simple zero configuration gemini server
5 
6 # SYNOPSIS
7 
8 **gmid**
9 \[**-h**]
10 \[**-c** *cert.pem*]
11 \[**-d** *docs*]
12 \[**-k** *key.pem*]
13 \[**-l** *logfile*]
14 \[**-x** *cgi-bin*]
15 
16 # DESCRIPTION
17 
18 **gmid**
19 is a very simple and minimal gemini server that can serve static files
20 and execute CGI scripts.
21 
22 **gmid**
23 will strip any sequence of
24 *../*
25 or trailing
26 *..*
27 in the requests made by clients, so it's impossible to serve content
28 outside the
29 *docs*
30 directory by mistake, and will also refuse to follow symlinks.
31 Furthermore, on
32 OpenBSD,
33 pledge(2)
34 and
35 unveil(2)
36 are used to ensure that
37 **gmid**
38 dosen't do anything else than read files from the given directory,
39 accept network connections and, optionally, execute CGI scripts.
40 
41 It should be noted that
42 **gmid**
43 is very simple in its implementation, and so it may not be appropriate
44 for serving sites with lots of users.
45 After all, the code is single threaded and use a single process,
46 although it can handle multiple requests concurrently.
47 
48 If a user request path is a directory,
49 **gmid**
50 will try to serve a
51 *index.gmi*
52 file inside that directory.
53 If not found, it will return an error 51 (not found) to the user.
54 
55 The options are as follows:
56 
57 **-c** *cert.pem*
58 
59 > The certificate to use, by default is
60 > *cert.pem*.
61 
62 **-d** *docs*
63 
64 > The root directory to serve.
65 > **gmid**
66 > won't serve any file that is outside that directory, by default
67 > *docs*.
68 
69 **-h**
70 
71 > Print the usage and exit.
72 
73 **-k** *key.pem*
74 
75 > The key for the certificate, by default is
76 > *key.pem*.
77 
78 **-l** *logfile*
79 
80 > log to the given file instead of the standard error.
81 
82 **-x** *dir*
83 
84 > Enable execution of CGI scripts inside the given directory (relative
85 > to the document root.)  Cannot be provided more than once.
86 
87 # CGI
88 
89 When CGI scripts are enabled for a directory, a request for an
90 executable file will execute it and fed its output to the client.
91 
92 The CGI scripts will inherit the environment from
93 **gmid**
94 with these additional variables set:
95 
96 `SERVER_SOFTWARE`
97 
98 > "gmid"
99 
100 `SERVER_PROTOCOL`
101 
102 > "gemini"
103 
104 `SERVER_PORT`
105 
106 > "1965"
107 
108 `PATH_INFO`
109 
110 > the request path
111 
112 `PATH_TRANSLATED`
113 
114 > the full path: the concatenation of the document root and the request
115 > path
116 
117 `QUERY_STRING`
118 
119 > the query string if present in the request URL, otherwise it
120 > won't be set.
121 
122 `REMOTE_ADDR`
123 
124 > the IP address of the client in dot notation
125 
126 # EXAMPLES
127 
128 To quickly getting started
129 
130 	$ # generate a cert and a key
131 	$ openssl req -x509 -newkey rsa:4096 -keyout key.pem \
132 	        -out cert.pem -days 365 -nodes
133 	$ mkdir docs
134 	$ cat <<EOF > docs/index.gmi
135 	# Hello world
136 	test paragraph...
137 	EOF
138 	$ gmid -c cert.pem -k key.pem -d docs
139 
140 Now you can visit gemini://localhost/ with your preferred gemini
141 client.
142 
143 To add some CGI scripts, assuming a setup similar to the previous
144 example, you can
145 
146 	$ mkdir docs/cgi-bin
147 	$ cat <<EOF > docs/cgi-bin/hello-world
148 	#!/bin/sh
149 	printf "20 text/plain\r\n"
150 	echo "hello world!"
151 	EOF
152 	$ gmid -x cgi-bin
153 
154 Note that the argument to the
155 **-x**
156 option is
157 *cgi-bin*
158 and not
159 *docs/cgi-bin*,
160 since it&#8217;s relative to the document root.
161 
162 # CAVEATS
163 
164 *	it doesn't support virtual hosts: the host part of the request URL is
165 	completely ignored.
166 
167 *	it doesn't fork in the background or anything like that.
168