💾 Archived View for kamid.omarpolo.com › tutorial.gmi captured on 2023-04-19 at 22:20:05. Gemini links have been rewritten to link to archived content

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

setup guide

1. create a dedicated user

kamid needs a dedicated ‘_kamid’ user to run. How to create an user depends on your operating system; for example on OpenBSD is:

# useradd -c kamid -d /var/empty -s /sbin/nologin _kamid

while on some GNU/linux systems:

# mkdir -p /var/empty
# useradd --system -d /var/empty -s /usr/sbin/nologin _kamid

Ideally the ‘_kamid’ user shouldn’t have a login shell and have an empty home.

2. create a configuration file

kamid looks for its configuration in ‘/etc/kamid.conf’ by default, but you can use the ‘-f’ flag to specify a different file. At the moment, kamid supports only 9p over TLS, so you need a TLS certificate too. A bare minimum configuration is:

pki localhost cert "/etc/ssl/localhost.crt"
pki localhost key "/etc/ssl/private/localhost.key"

table users { "SHA256:..." => "op" }

listen on localhost port 1337 tls pki localhost auth <users>

"SHA256:..." is the hash of the client certificate for the user "op" and is used for authentication. The configuration is quite flexible, and allows to create “virtual users” and map those to custom home directories too.

An easy way to generate certificates and obtain their fingerprint is by using the scripts ‘fingerprint’ and ‘gencert’ in the ‘contrib’ directory:

% ./contrib/gencert foo
Generating a 4096 bit RSA private key
[...]
writing new private key to 'foo'
-----
% ./contrib/fingerprint foo
SHA256:c043a39b4c65993f03b8df46116a692392399e3be0eb233f4efd74cd53540370

To check the configuration for syntax errors, execute:

$ kamid -n

3. run the daemon

With all the previous steps done, running the daemon is as easy as:

# kamid

use ‘-d’ to keep kamid in the foreground (i.e. not daemonize) and ‘-v’ to increase the verbosity.

Congratulations! Your kamid instance is up and running.

4. connecting to the server

There are quite a few clients for 9p, even if not all may support 9p over TLS with client certificates. As part of kamid there is a small ftp(1)-like client called ‘kamiftp’:

$ kamiftp -C foo localhost

(‘foo’ is the certificate previously generated)

Check out kamiftp(1) for usage. Alternatively, try tinmop! It’s a ncurses application that supports a plethora of protocols: it’s a gemini browser, a pleroma client and also 9p-over-TLS capable!

kamiftp(1)

tinmop