1 21dc3794 2022-01-28 op # gmid quickstart guide
  2 7c6bf71d 2021-10-11 op 
  3 acc86215 2024-01-07 op The aim of this “quickstart” guide is to get your capsule up and running.
  4 0111ad5d 2021-10-09 op 
  5 acc86215 2024-01-07 op gmid needs a configuration file to operate.  The format is quite flexible and carefully described in the gmid.conf(5) manpage, but to start this should be enough:
  6 0111ad5d 2021-10-09 op 
  7 0111ad5d 2021-10-09 op ```sample configuration file
  8 0111ad5d 2021-10-09 op # /etc/gmid.conf
  9 0111ad5d 2021-10-09 op 
 10 0111ad5d 2021-10-09 op server "example.com" {
 11 acc86215 2024-01-07 op 	listen on * port 1965
 12 33c4c3a5 2021-10-13 op 	cert "/etc/ssl/example.com.pem"
 13 33c4c3a5 2021-10-13 op 	key  "/etc/ssl/private/example.com.key"
 14 33c4c3a5 2021-10-13 op 
 15 33c4c3a5 2021-10-13 op 	# path to the root directory of your capsule
 16 0111ad5d 2021-10-09 op 	root "/var/gemini/example.com"
 17 0111ad5d 2021-10-09 op }
 18 0111ad5d 2021-10-09 op ```
 19 0111ad5d 2021-10-09 op 
 20 acc86215 2024-01-07 op This will have gmid listening on any address on port 1965 and serving the directory /var/gemini/example.com.
 21 acc86215 2024-01-07 op 
 22 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.
 23 0111ad5d 2021-10-09 op 
 24 ffd92e63 2022-04-07 op One way to generate self-signed certificates is to use openssl(1), but contrib/gencert is easier to use:
 25 ffd92e63 2022-04-07 op 
 26 2573332d 2022-07-07 op => TREE/contrib/gencert contrib/gencert
 27 0111ad5d 2021-10-09 op 
 28 0111ad5d 2021-10-09 op ```generate a certificate using contrib/gencert
 29 0111ad5d 2021-10-09 op $ ./contrib/gencert example.com
 30 0111ad5d 2021-10-09 op Generating a 4096 bit RSA private key
 31 0111ad5d 2021-10-09 op .................................................++++
 32 0111ad5d 2021-10-09 op ..........++++
 33 0111ad5d 2021-10-09 op writing new private key to './example.com.key'
 34 0111ad5d 2021-10-09 op -----
 35 0111ad5d 2021-10-09 op 
 36 0111ad5d 2021-10-09 op Generated files:
 37 0111ad5d 2021-10-09 op         ./example.com.pem : certificate
 38 0111ad5d 2021-10-09 op         ./example.com.key : private key
 39 0111ad5d 2021-10-09 op ```
 40 0111ad5d 2021-10-09 op 
 41 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.
 42 0111ad5d 2021-10-09 op 
 43 ffd92e63 2022-04-07 op One place could be ‘/etc/ssl/’
 44 0111ad5d 2021-10-09 op 
 45 33c4c3a5 2021-10-13 op ```how to save the certificate and private key in /etc/ssl
 46 33c4c3a5 2021-10-13 op # mkdir -p /etc/ssl/private
 47 33c4c3a5 2021-10-13 op # chown 700 /etc/ssl/private
 48 33c4c3a5 2021-10-13 op # mv example.com.pem /etc/ssl/
 49 33c4c3a5 2021-10-13 op # mv example.com.key /etc/ssl/private/
 50 33c4c3a5 2021-10-13 op ```
 51 33c4c3a5 2021-10-13 op 
 52 0111ad5d 2021-10-09 op Then running gmid is as easy as
 53 0111ad5d 2021-10-09 op 
 54 0111ad5d 2021-10-09 op ```running gmid
 55 ffd92e63 2022-04-07 op # gmid -c /etc/gmid.conf
 56 0111ad5d 2021-10-09 op ```
 57 0111ad5d 2021-10-09 op 
 58 fc4b58d4 2021-10-11 op Congratulations, your capsule is online!
 59 0111ad5d 2021-10-09 op 
 60 fc4b58d4 2021-10-11 op 
 61 0111ad5d 2021-10-09 op ## Securing your gmid installation
 62 0111ad5d 2021-10-09 op 
 63 ffd92e63 2022-04-07 op gmid employs various techniques to prevent the damage caused by bugs but some steps needs to be done manually.
 64 0111ad5d 2021-10-09 op 
 65 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.
 66 0111ad5d 2021-10-09 op 
 67 0111ad5d 2021-10-09 op 
 68 0111ad5d 2021-10-09 op ### A dedicated user
 69 0111ad5d 2021-10-09 op 
 70 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
 71 0111ad5d 2021-10-09 op 
 72 db48d276 2022-05-02 op For example, on OpenBSD a ‘_gmid’ user can be created with:
 73 ffd92e63 2022-04-07 op 
 74 db48d276 2022-05-02 op ```
 75 db48d276 2022-05-02 op # useradd -c gmid -d /var/empty -s /sbin/nologin _gmid
 76 db48d276 2022-05-02 op ```
 77 db48d276 2022-05-02 op 
 78 db48d276 2022-05-02 op while on most GNU/linux systems it's:
 79 db48d276 2022-05-02 op 
 80 0111ad5d 2021-10-09 op ```how to create the gmid user
 81 35340c9f 2021-10-09 op # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
 82 0111ad5d 2021-10-09 op ```
 83 0111ad5d 2021-10-09 op 
 84 db48d276 2022-05-02 op or if you use systemd-sysusers:
 85 3c04ffc0 2022-03-09 op 
 86 3c04ffc0 2022-03-09 op ```how to create the gmid user, using systemd-sysusers
 87 3c04ffc0 2022-03-09 op # systemd-sysusers contrib/gmid.sysusers
 88 3c04ffc0 2022-03-09 op ```
 89 3c04ffc0 2022-03-09 op 
 90 0111ad5d 2021-10-09 op Please consult your OS documentation for more information on the matter.
 91 0111ad5d 2021-10-09 op 
 92 0111ad5d 2021-10-09 op The configuration then needs to be adjusted to include the ‘user’ directive at the top:
 93 0111ad5d 2021-10-09 op 
 94 0111ad5d 2021-10-09 op ```how to use the ‘user’ option
 95 0111ad5d 2021-10-09 op # /etc/gmid.conf
 96 0111ad5d 2021-10-09 op user "gmid"
 97 0111ad5d 2021-10-09 op 
 98 0111ad5d 2021-10-09 op server "example.com" { … }
 99 0111ad5d 2021-10-09 op ```
100 0111ad5d 2021-10-09 op 
101 db48d276 2022-05-02 op 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.
102 0111ad5d 2021-10-09 op 
103 0111ad5d 2021-10-09 op 
104 0111ad5d 2021-10-09 op ### chroot
105 0111ad5d 2021-10-09 op 
106 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.
107 0111ad5d 2021-10-09 op 
108 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.
109 0111ad5d 2021-10-09 op 
110 acc86215 2024-01-07 op Using a chroot may complicate the setup since eventual FastCGI socket or files needed for DNS resolution need to be installed or copied inside the chroot too.
111 0111ad5d 2021-10-09 op 
112 0111ad5d 2021-10-09 op The chroot feature requires a dedicate user, see the previous section.
113 0111ad5d 2021-10-09 op 
114 0111ad5d 2021-10-09 op To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
115 0111ad5d 2021-10-09 op 
116 0111ad5d 2021-10-09 op ```how to use the ‘chroot’ option
117 0111ad5d 2021-10-09 op # /etc/gmid.conf
118 0111ad5d 2021-10-09 op 
119 35340c9f 2021-10-09 op user "gmid"
120 35340c9f 2021-10-09 op 
121 0111ad5d 2021-10-09 op # the given directory, /var/gemini in this case, must exists.
122 0111ad5d 2021-10-09 op chroot "/var/gemini"
123 0111ad5d 2021-10-09 op ```
124 0111ad5d 2021-10-09 op 
125 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!
126 0111ad5d 2021-10-09 op 
127 0111ad5d 2021-10-09 op For example, given the following configuration:
128 0111ad5d 2021-10-09 op 
129 0111ad5d 2021-10-09 op ```example configuration using chroot
130 0111ad5d 2021-10-09 op # /etc/gmid.conf
131 0111ad5d 2021-10-09 op 
132 0111ad5d 2021-10-09 op user "gmid"
133 0111ad5d 2021-10-09 op chroot "/var/gemini"
134 0111ad5d 2021-10-09 op 
135 0111ad5d 2021-10-09 op server "example.com" {
136 acc86215 2024-01-07 op 	listen on *
137 0111ad5d 2021-10-09 op 	cert "/etc/ssl/example.com.pem"
138 0111ad5d 2021-10-09 op 	key  "/etc/ssl/example.com.key"
139 0111ad5d 2021-10-09 op 	root "/example.com"
140 0111ad5d 2021-10-09 op }
141 0111ad5d 2021-10-09 op ```
142 0111ad5d 2021-10-09 op 
143 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/”.