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