1 21dc3794 2022-01-28 op # gmid quickstart guide
3 ffd92e63 2022-04-07 op gmid can be run in two different modes:
5 ffd92e63 2022-04-07 op * configless: a quick way to serve a directory tree from the shell, useful for testing purposes
6 0111ad5d 2021-10-09 op * daemon mode: gmid reads the configuration file and runs in the background
8 0111ad5d 2021-10-09 op To run gmid in the “configless” mode, just type:
10 0111ad5d 2021-10-09 op ```serve a directory tree from the shell
11 0111ad5d 2021-10-09 op $ gmid path/to/dir
14 540d05de 2021-10-09 op gmid will then generate a certificate inside ~/.local/share/gmid and serve the given directory locally.
17 fc4b58d4 2021-10-11 op ## Setting up a capsule with gmid
19 c57dc42b 2022-01-05 op To host a Gemini capsule you need to run gmid in “daemon” mode, and so a configuration file is needed. The format of the configuration file is described in the manpage and is quite flexible, but something like the following should be enough to start:
21 0111ad5d 2021-10-09 op ```sample configuration file
22 0111ad5d 2021-10-09 op # /etc/gmid.conf
24 0111ad5d 2021-10-09 op server "example.com" {
25 33c4c3a5 2021-10-13 op cert "/etc/ssl/example.com.pem"
26 33c4c3a5 2021-10-13 op key "/etc/ssl/private/example.com.key"
28 33c4c3a5 2021-10-13 op # path to the root directory of your capsule
29 0111ad5d 2021-10-09 op root "/var/gemini/example.com"
33 ffd92e63 2022-04-07 op A TLS certificate is also needed. There are many way to obtain one (acme-client, certbot, ...) but within the Geminispace is common to use self-signed ones.
35 ffd92e63 2022-04-07 op One way to generate self-signed certificates is to use openssl(1), but contrib/gencert is easier to use:
37 0111ad5d 2021-10-09 op => https://git.omarpolo.com/gmid/tree/contrib/gencert contrib/gencert
39 0111ad5d 2021-10-09 op ```generate a certificate using contrib/gencert
40 0111ad5d 2021-10-09 op $ ./contrib/gencert example.com
41 0111ad5d 2021-10-09 op Generating a 4096 bit RSA private key
42 0111ad5d 2021-10-09 op .................................................++++
43 0111ad5d 2021-10-09 op ..........++++
44 0111ad5d 2021-10-09 op writing new private key to './example.com.key'
47 0111ad5d 2021-10-09 op Generated files:
48 0111ad5d 2021-10-09 op ./example.com.pem : certificate
49 0111ad5d 2021-10-09 op ./example.com.key : private key
52 33c4c3a5 2021-10-13 op Move ‘example.com.pem’ and ‘example.com.key’ to a safe place and double check that the ‘cert’ and ‘key’ options in the configuration points to these files.
54 ffd92e63 2022-04-07 op One place could be ‘/etc/ssl/’
56 33c4c3a5 2021-10-13 op ```how to save the certificate and private key in /etc/ssl
57 33c4c3a5 2021-10-13 op # mkdir -p /etc/ssl/private
58 33c4c3a5 2021-10-13 op # chown 700 /etc/ssl/private
59 33c4c3a5 2021-10-13 op # mv example.com.pem /etc/ssl/
60 33c4c3a5 2021-10-13 op # mv example.com.key /etc/ssl/private/
63 0111ad5d 2021-10-09 op Then running gmid is as easy as
65 0111ad5d 2021-10-09 op ```running gmid
66 ffd92e63 2022-04-07 op # gmid -c /etc/gmid.conf
69 fc4b58d4 2021-10-11 op Congratulations, your capsule is online!
72 0111ad5d 2021-10-09 op ## Securing your gmid installation
74 ffd92e63 2022-04-07 op gmid employs various techniques to prevent the damage caused by bugs but some steps needs to be done manually.
76 ffd92e63 2022-04-07 op If gmid was installed from your distribution package manager chance are that it already does all of this and is also providing a service to easily run gmid (e.g. a rc script, a systemd unit file, …) Otherwise, it’s heavily suggested to create at least a dedicated user.
79 0111ad5d 2021-10-09 op ### A dedicated user
81 ffd92e63 2022-04-07 op Ideally, gmid should be started as root and then drop privileges. This allows to save the certificates in a directory that's readable only by root
83 ffd92e63 2022-04-07 op For example, on GNU/linux systems a ‘gmid’ user can be created with:
85 0111ad5d 2021-10-09 op ```how to create the gmid user
86 35340c9f 2021-10-09 op # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
89 3c04ffc0 2022-03-09 op If you use systemd-sysusers:
91 3c04ffc0 2022-03-09 op ```how to create the gmid user, using systemd-sysusers
92 3c04ffc0 2022-03-09 op # systemd-sysusers contrib/gmid.sysusers
95 0111ad5d 2021-10-09 op Please consult your OS documentation for more information on the matter.
97 0111ad5d 2021-10-09 op The configuration then needs to be adjusted to include the ‘user’ directive at the top:
99 0111ad5d 2021-10-09 op ```how to use the ‘user’ option
100 0111ad5d 2021-10-09 op # /etc/gmid.conf
103 0111ad5d 2021-10-09 op server "example.com" { … }
106 fc4b58d4 2021-10-11 op gmid then needs to be started with root privileges, but will then switch to the provided user automatically. If by accident the ‘user’ option is omitted and gmid is running as root, it will complain loudly in the logs.
111 0111ad5d 2021-10-09 op It’s a common practice for system daemons to chroot themselves into a directory. From here on I’ll assume /var/gemini, but it can be any directory.
113 fc4b58d4 2021-10-11 op A chroot on UNIX-like OS is an operation that changes the “apparent” root directory (i.e. the “/”) from the current process and its child. Think of it like imprisoning a process into a directory and never letting it escape until it terminates.
115 fc4b58d4 2021-10-11 op Using a chroot may complicate the use of CGI scripts, because then all the dependencies of the scripts (sh, perl, libraries…) need to be installed inside the chroot too. For this very reason gmid supports FastCGI.
117 0111ad5d 2021-10-09 op The chroot feature requires a dedicate user, see the previous section.
119 0111ad5d 2021-10-09 op To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
121 0111ad5d 2021-10-09 op ```how to use the ‘chroot’ option
122 0111ad5d 2021-10-09 op # /etc/gmid.conf
126 0111ad5d 2021-10-09 op # the given directory, /var/gemini in this case, must exists.
127 0111ad5d 2021-10-09 op chroot "/var/gemini"
130 0111ad5d 2021-10-09 op Note that once ‘chroot’ is in place, every ‘root’ directive is implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
132 0111ad5d 2021-10-09 op For example, given the following configuration:
134 0111ad5d 2021-10-09 op ```example configuration using chroot
135 0111ad5d 2021-10-09 op # /etc/gmid.conf
138 0111ad5d 2021-10-09 op chroot "/var/gemini"
140 0111ad5d 2021-10-09 op server "example.com" {
141 0111ad5d 2021-10-09 op cert "/etc/ssl/example.com.pem"
142 0111ad5d 2021-10-09 op key "/etc/ssl/example.com.key"
143 0111ad5d 2021-10-09 op root "/example.com"
147 0111ad5d 2021-10-09 op The certificate and the key path are the specified ones, but the root directory of the virtual host is actually “/var/gemini/example.com/”.