💾 Archived View for gmid.omarpolo.com › quickstart.gmi captured on 2024-02-05 at 09:23:23. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

contrib

faq

gmid quickstart guide

The aim of this “quickstart” guide is to get your capsule up and running.

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:

# /etc/gmid.conf

server "example.com" {
	listen on * port 1965
	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"
}

This will have gmid listening on any address on port 1965 and serving the directory /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:

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/’

# 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

# 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 OpenBSD a ‘_gmid’ user can be created with:

# useradd -c gmid -d /var/empty -s /sbin/nologin _gmid

while on most GNU/linux systems it's:

# useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid

or if you use 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:

# /etc/gmid.conf
user "gmid"

server "example.com" { … }

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.

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 setup since eventual FastCGI socket or files needed for DNS resolution need to be installed or copied inside the chroot too.

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:

# /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:

# /etc/gmid.conf

user "gmid"
chroot "/var/gemini"

server "example.com" {
	listen on *
	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/”.