1 # gmid quickstart
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 a capsule before uploading it
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 To run gmid in daemon mode a configuration file is needed.  The format of the configuration file is described in the manpage and is quite flexible, but for simple setup something like the following should be enough:
17 
18 ```sample configuration file
19 # /etc/gmid.conf
20 
21 server "example.com" {
22 	cert "/path/to/certificate"
23 	key  "/path/to/private-key"
24 	root "/var/gemini/example.com"
25 }
26 ```
27 
28 A X.509 (TLS) certificate can be generated using contrib/gencert
29 
30 => https://git.omarpolo.com/gmid/tree/contrib/gencert contrib/gencert
31 
32 ```generate a certificate using contrib/gencert
33 $ ./contrib/gencert example.com
34 Generating a 4096 bit RSA private key
35 .................................................++++
36 ..........++++
37 writing new private key to './example.com.key'
38 -----
39 
40 Generated files:
41         ./example.com.pem : certificate
42         ./example.com.key : private key
43 ```
44 
45 Optionally, move ‘example.com.pem’ and ‘example.com.key’ to another location.
46 
47 Make sure that the ‘cert’ and ‘key’ options in the configuration file points to these files.
48 
49 Then running gmid is as easy as
50 
51 ```running gmid
52 $ gmid -c /etc/gmid.conf
53 ```
54 
55 
56 ## Securing your gmid installation
57 
58 gmid employs various techniques to prevent the damage caused by bugs, but some steps needs to be done manually.
59 
60 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 run gmid automatically (e.g. a systemd unit file, a rc script, …)  Otherwise, it’s heavily suggested to create at least a dedicated user.
61 
62 
63 ### A dedicated user
64 
65 Ideally, gmid should be started with root privileges and drop privileges to a local user.  This way, the created certificates can be readable only by root.  For example, on GNU/linux systems a ‘gmid’ user can be created with:
66 
67 ```how to create the gmid user
68 # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
69 ```
70 
71 Please consult your OS documentation for more information on the matter.
72 
73 The configuration then needs to be adjusted to include the ‘user’ directive at the top:
74 
75 ```how to use the ‘user’ option
76 # /etc/gmid.conf
77 user "gmid"
78 
79 server "example.com" { … }
80 ```
81 
82 gmid then needs to be started with root privileges, but will then switch to the provided user automatically.  If by accident the ‘user’ is forgotten and gmid is running as root, it will complain loudly in the logs.
83 
84 
85 ### chroot
86 
87 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.
88 
89 A chroot on UNIX-like OS is an operation that changes the “apparent” root directory (i.e. “/”) 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.
90 
91 Using a chroot may complicate the use of CGI scripts, because then all the dependencies of the scripts (like sh, perl, libraries…) need to be installed inside the chroot too.  For this very reason gmid supports FastCGI.
92 
93 The chroot feature requires a dedicate user, see the previous section.
94 
95 To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
96 
97 ```how to use the ‘chroot’ option
98 # /etc/gmid.conf
99 
100 user "gmid"
101 
102 # the given directory, /var/gemini in this case, must exists.
103 chroot "/var/gemini"
104 ```
105 
106 Note that once ‘chroot’ is in place, every ‘root’ directive is implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
107 
108 For example, given the following configuration:
109 
110 ```example configuration using chroot
111 # /etc/gmid.conf
112 
113 user "gmid"
114 chroot "/var/gemini"
115 
116 server "example.com" {
117 	cert "/etc/ssl/example.com.pem"
118 	key  "/etc/ssl/example.com.key"
119 	root "/example.com"
120 }
121 ```
122 
123 The certificate and the key path are the specified ones, but the root directory of the virtual host is actually “/var/gemini/example.com/”.