1 # gmid quickstart guide
2 
3 gmid can be run in two different modes:
4 
5 * configless: a quick way to serve a directory tree from the shell, useful for testing purposes
6 * daemon mode: gmid reads the configuration file and runs in the background
7 
8 To run gmid in the “configless” mode, just type:
9 
10 ```serve a directory tree from the shell
11 $ gmid path/to/dir
12 ```
13 
14 gmid will then generate a certificate inside ~/.local/share/gmid and serve the given directory locally.
15 
16 
17 ## Setting up a capsule with gmid
18 
19 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:
20 
21 ```sample configuration file
22 # /etc/gmid.conf
23 
24 server "example.com" {
25 	cert "/etc/ssl/example.com.pem"
26 	key  "/etc/ssl/private/example.com.key"
27 
28 	# path to the root directory of your capsule
29 	root "/var/gemini/example.com"
30 }
31 ```
32 
33 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.
34 
35 One way to generate self-signed certificates is to use openssl(1), but contrib/gencert is easier to use:
36 
37 => TREE/contrib/gencert contrib/gencert
38 
39 ```generate a certificate using contrib/gencert
40 $ ./contrib/gencert example.com
41 Generating a 4096 bit RSA private key
42 .................................................++++
43 ..........++++
44 writing new private key to './example.com.key'
45 -----
46 
47 Generated files:
48         ./example.com.pem : certificate
49         ./example.com.key : private key
50 ```
51 
52 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.
53 
54 One place could be ‘/etc/ssl/’
55 
56 ```how to save the certificate and private key in /etc/ssl
57 # mkdir -p /etc/ssl/private
58 # chown 700 /etc/ssl/private
59 # mv example.com.pem /etc/ssl/
60 # mv example.com.key /etc/ssl/private/
61 ```
62 
63 Then running gmid is as easy as
64 
65 ```running gmid
66 # gmid -c /etc/gmid.conf
67 ```
68 
69 Congratulations, your capsule is online!
70 
71 
72 ## Securing your gmid installation
73 
74 gmid employs various techniques to prevent the damage caused by bugs but some steps needs to be done manually.
75 
76 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.
77 
78 
79 ### A dedicated user
80 
81 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
82 
83 For example, on OpenBSD a ‘_gmid’ user can be created with:
84 
85 ```
86 # useradd -c gmid -d /var/empty -s /sbin/nologin _gmid
87 ```
88 
89 while on most GNU/linux systems it's:
90 
91 ```how to create the gmid user
92 # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
93 ```
94 
95 or if you use systemd-sysusers:
96 
97 ```how to create the gmid user, using systemd-sysusers
98 # systemd-sysusers contrib/gmid.sysusers
99 ```
100 
101 Please consult your OS documentation for more information on the matter.
102 
103 The configuration then needs to be adjusted to include the ‘user’ directive at the top:
104 
105 ```how to use the ‘user’ option
106 # /etc/gmid.conf
107 user "gmid"
108 
109 server "example.com" { … }
110 ```
111 
112 Now gmid needs to be started with root privileges but will 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.
113 
114 
115 ### chroot
116 
117 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.
118 
119 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.
120 
121 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.
122 
123 The chroot feature requires a dedicate user, see the previous section.
124 
125 To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
126 
127 ```how to use the ‘chroot’ option
128 # /etc/gmid.conf
129 
130 user "gmid"
131 
132 # the given directory, /var/gemini in this case, must exists.
133 chroot "/var/gemini"
134 ```
135 
136 Note that once ‘chroot’ is in place, every ‘root’ directive is implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
137 
138 For example, given the following configuration:
139 
140 ```example configuration using chroot
141 # /etc/gmid.conf
142 
143 user "gmid"
144 chroot "/var/gemini"
145 
146 server "example.com" {
147 	cert "/etc/ssl/example.com.pem"
148 	key  "/etc/ssl/example.com.key"
149 	root "/example.com"
150 }
151 ```
152 
153 The certificate and the key path are the specified ones, but the root directory of the virtual host is actually “/var/gemini/example.com/”.