1 0111ad5d 2021-10-09 op <!doctype html>
2 0111ad5d 2021-10-09 op <html lang="en">
4 35340c9f 2021-10-09 op <title>gmid quickstart</title>
5 0111ad5d 2021-10-09 op <meta charset="utf8" />
6 0111ad5d 2021-10-09 op <meta name="viewport" content="width=device-width, initial-scale=1" />
9 0111ad5d 2021-10-09 op font-family: monospace;
10 0111ad5d 2021-10-09 op font-size: 14px;
11 0111ad5d 2021-10-09 op max-width: 780px;
12 0111ad5d 2021-10-09 op margin: 0 auto;
13 0111ad5d 2021-10-09 op padding: 20px;
14 0111ad5d 2021-10-09 op padding-bottom: 80px;
18 0111ad5d 2021-10-09 op content: "# ";
22 0111ad5d 2021-10-09 op margin-top: 40px;
26 0111ad5d 2021-10-09 op content: "## ";
30 0111ad5d 2021-10-09 op content: "### ";
38 0111ad5d 2021-10-09 op blockquote::before {
39 0111ad5d 2021-10-09 op content: "> ";
42 0111ad5d 2021-10-09 op blockquote p {
43 0111ad5d 2021-10-09 op font-style: italic;
44 0111ad5d 2021-10-09 op display: inline;
47 0111ad5d 2021-10-09 op p.link::before {
48 0111ad5d 2021-10-09 op content: "→ ";
51 0111ad5d 2021-10-09 op strong::before { content: "*" }
52 0111ad5d 2021-10-09 op strong::after { content: "*" }
57 0111ad5d 2021-10-09 op background-color: #222;
59 0111ad5d 2021-10-09 op display: block;
60 0111ad5d 2021-10-09 op margin: 2em auto;
64 0111ad5d 2021-10-09 op border-radius: 5px;
68 0111ad5d 2021-10-09 op overflow: auto;
69 0111ad5d 2021-10-09 op padding: 1rem;
70 0111ad5d 2021-10-09 op background-color: #f0f0f0;
71 0111ad5d 2021-10-09 op border-radius: 3px;
75 0111ad5d 2021-10-09 op display: flex;
76 0111ad5d 2021-10-09 op flex-direction: row;
77 0111ad5d 2021-10-09 op justify-content: center;
81 0111ad5d 2021-10-09 op color: #9d109d;
85 0111ad5d 2021-10-09 op display: block;
86 0111ad5d 2021-10-09 op margin: 0 auto;
87 0111ad5d 2021-10-09 op max-width: 100%;
90 0111ad5d 2021-10-09 op @media (prefers-color-scheme: dark) {
92 0111ad5d 2021-10-09 op background-color: #222;
101 0111ad5d 2021-10-09 op background-color: #ddd;
105 0111ad5d 2021-10-09 op background-color: #353535;
109 0111ad5d 2021-10-09 op color: #ff4cff;
113 0111ad5d 2021-10-09 op @media (max-width: 400px) {
114 0111ad5d 2021-10-09 op pre.banner { font-size: 9px; }
117 0111ad5d 2021-10-09 op @media (max-width: 500px) {
118 0111ad5d 2021-10-09 op pre.banner { font-size: 10px; }
125 0111ad5d 2021-10-09 op <a href="/">Home</a> |
126 0111ad5d 2021-10-09 op <a href="contrib.html">contrib</a> |
128 0111ad5d 2021-10-09 op <a href="gmid.1.html">docs</a>
131 0111ad5d 2021-10-09 op <h1>gmid quickstart</h1>
132 0111ad5d 2021-10-09 op <p>gmid can be run in two different “modes”:</p>
134 0111ad5d 2021-10-09 op <dt>configless:</dt>
136 0111ad5d 2021-10-09 op a quick way to serve a directory tree from the shell, useful
137 0111ad5d 2021-10-09 op for testing a capsule before uploading it
139 0111ad5d 2021-10-09 op <dt>daemon mode:</dt>
141 0111ad5d 2021-10-09 op gmid reads the configuration file and runs in the background
144 0111ad5d 2021-10-09 op <p>To run gmid in the “configless” mode, just type:</p>
145 0111ad5d 2021-10-09 op <pre>$ gmid path/to/dir</pre>
147 0111ad5d 2021-10-09 op gmid will then generate a certificate inside ~/.local/share/gmid
148 540d05de 2021-10-09 op and serve the given directory locally.
150 fc4b58d4 2021-10-11 op <h2>Setting up a capsule with gmid</h2>
151 fc4b58d4 2021-10-11 op <p>To host a Gemini capsule you need to run gmid in “daemon” mode.</p>
153 0111ad5d 2021-10-09 op To run gmid in daemon mode a configuration file is needed. The
154 0111ad5d 2021-10-09 op format of the configuration file is described in the manpage and
155 fc4b58d4 2021-10-11 op is quite flexible, but something like the following should be
156 fc4b58d4 2021-10-11 op enough to start:
158 0111ad5d 2021-10-09 op <pre># /etc/gmid.conf
160 0111ad5d 2021-10-09 op server "example.com" {
161 33c4c3a5 2021-10-13 op cert "/etc/ssl/example.com.pem"
162 33c4c3a5 2021-10-13 op key "/etc/ssl/private/example.com/key"
164 33c4c3a5 2021-10-13 op # path to the root directory of your capsule
165 0111ad5d 2021-10-09 op root "/var/gemini/example.com"
168 33c4c3a5 2021-10-13 op A certificate is needed for the capsule. Generate one for
170 0111ad5d 2021-10-09 op <a href="https://git.omarpolo.com/gmid/tree/contrib/gencert">contrib/gencert</a>:
172 0111ad5d 2021-10-09 op <pre>$ ./contrib/gencert example.com
173 0111ad5d 2021-10-09 op Generating a 4096 bit RSA private key
174 0111ad5d 2021-10-09 op .................................................++++
175 0111ad5d 2021-10-09 op ..........++++
176 0111ad5d 2021-10-09 op writing new private key to './example.com.key'
179 0111ad5d 2021-10-09 op Generated files:
180 0111ad5d 2021-10-09 op ./example.com.pem : certificate
181 0111ad5d 2021-10-09 op ./example.com.key : private key</pre>
183 33c4c3a5 2021-10-13 op Move ‘example.com.pem’ and ‘example.com.key’ to a safe place and
184 33c4c3a5 2021-10-13 op double check that the ‘cert’ and ‘key’ options in the
185 33c4c3a5 2021-10-13 op configuration points to these files.
187 33c4c3a5 2021-10-13 op <p>For example, save them in ‘/etc/ssl/’ (as root)</p>
188 33c4c3a5 2021-10-13 op <pre># mkdir -p /etc/ssl/private
189 33c4c3a5 2021-10-13 op # chown 700 /etc/ssl/private
190 33c4c3a5 2021-10-13 op # mv example.com.pem /etc/ssl/
191 33c4c3a5 2021-10-13 op # mv example.com.key /etc/ssl/private/</pre>
193 0111ad5d 2021-10-09 op Make sure that the ‘cert’ and ‘key’ options in the configuration
194 0111ad5d 2021-10-09 op file points to these files.
196 0111ad5d 2021-10-09 op <p>Then running gmid is as easy as</p>
197 0111ad5d 2021-10-09 op <pre>$ gmid -c /etc/gmid.conf</pre>
198 fc4b58d4 2021-10-11 op <p>Congratulations, your capsule is online!</p>
199 0111ad5d 2021-10-09 op <h2>Securing your gmid installation</h2>
201 0111ad5d 2021-10-09 op gmid employs various techniques to prevent the damage caused by
202 0111ad5d 2021-10-09 op bugs, but some steps needs to be done manually.
205 0111ad5d 2021-10-09 op If gmid was installed from your distribution package manager,
206 0111ad5d 2021-10-09 op chance are that it already does all of this and is also
207 33c4c3a5 2021-10-13 op providing a service to run gmid automatically (e.g. a rc script,
208 33c4c3a5 2021-10-13 op a systemd unit file …) Otherwise, it’s heavily suggested to
209 0111ad5d 2021-10-09 op create at least a dedicated user.
211 0111ad5d 2021-10-09 op <h3>A dedicated user</h3>
213 fc4b58d4 2021-10-11 op Ideally, gmid should be started as root and drop privileges to a
214 fc4b58d4 2021-10-11 op local user. This way, the certificates can be readable only by
215 fc4b58d4 2021-10-11 op root. For example, on GNU/linux systems a ‘gmid’ user can be
216 fc4b58d4 2021-10-11 op created with:
218 35340c9f 2021-10-09 op <pre># useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid</pre>
220 0111ad5d 2021-10-09 op Please consult your OS documentation for more information on the
224 0111ad5d 2021-10-09 op The configuration then needs to be adjusted to include the
225 0111ad5d 2021-10-09 op ‘user’ directive at the top:
227 0111ad5d 2021-10-09 op <pre># /etc/gmid.conf
230 0111ad5d 2021-10-09 op server "example.com" { … }</pre>
232 0111ad5d 2021-10-09 op gmid then needs to be started with root privileges, but will
233 0111ad5d 2021-10-09 op then switch to the provided user automatically. If by accident
234 fc4b58d4 2021-10-11 op the ‘user’ option is omitted and gmid is running as root, it
235 fc4b58d4 2021-10-11 op will complain loudly in the logs.
237 0111ad5d 2021-10-09 op <h3>chroot</h3>
239 0111ad5d 2021-10-09 op It’s a common practice for system daemons to chroot themselves
240 0111ad5d 2021-10-09 op into a directory. From here on I’ll assume /var/gemini, but it
241 0111ad5d 2021-10-09 op can be any directory.
244 0111ad5d 2021-10-09 op A chroot on UNIX-like OS is an operation that changes the
245 fc4b58d4 2021-10-11 op “apparent” root directory (i.e. the “/”) from the current
246 fc4b58d4 2021-10-11 op process and its child. Think of it like imprisoning a process
247 fc4b58d4 2021-10-11 op into a directory and never letting it escape until it
251 0111ad5d 2021-10-09 op Using a chroot may complicate the use of CGI scripts, because
252 fc4b58d4 2021-10-11 op then all the dependencies of the scripts (sh, perl, libraries…)
253 fc4b58d4 2021-10-11 op need to be installed inside the chroot too. For this very
254 fc4b58d4 2021-10-11 op reason gmid supports FastCGI.
257 0111ad5d 2021-10-09 op The chroot feature requires a dedicate user, see the previous
261 0111ad5d 2021-10-09 op To chroot gmid inside a directory, use the ‘chroot’ directive in
262 0111ad5d 2021-10-09 op the configuration file:
264 0111ad5d 2021-10-09 op <pre># /etc/gmid.conf
268 0111ad5d 2021-10-09 op # the given directory, /var/gemini in this case, must exists.
269 0111ad5d 2021-10-09 op chroot "/var/gemini"</pre>
271 0111ad5d 2021-10-09 op Note that once ‘chroot’ is in place, every ‘root’ directive is
272 0111ad5d 2021-10-09 op implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
274 0111ad5d 2021-10-09 op <p>For example, given the following configuration:</p>
275 0111ad5d 2021-10-09 op <pre># /etc/gmid.conf
278 0111ad5d 2021-10-09 op chroot "/var/gemini"
280 0111ad5d 2021-10-09 op server "example.com" {
281 0111ad5d 2021-10-09 op cert "/etc/ssl/example.com.pem"
282 0111ad5d 2021-10-09 op key "/etc/ssl/example.com.key"
283 0111ad5d 2021-10-09 op root "/example.com"
286 0111ad5d 2021-10-09 op The certificate and the key path are the specified ones, but the
287 0111ad5d 2021-10-09 op root directory of the virtual host is actually
288 0111ad5d 2021-10-09 op “/var/gemini/example.com/”.