3 34845b8f 2022-01-23 op ## 1. create a dedicated user
5 a3f21475 2022-02-09 op kamid needs a dedicated ‘_kamid’ user to run. How to create an user depends on your operating system; for example on OpenBSD is:
8 34845b8f 2022-01-23 op # useradd -c kamid -d /var/empty -s /sbin/nologin _kamid
11 a3f21475 2022-02-09 op while on some GNU/linux systems:
14 a3f21475 2022-02-09 op # mkdir -p /var/empty
15 a3f21475 2022-02-09 op # useradd --system -d /var/empty -s /usr/sbin/nologin _kamid
18 34845b8f 2022-01-23 op Ideally the ‘_kamid’ user shouldn’t have a login shell and have an empty home.
21 34845b8f 2022-01-23 op ## 2. create a configuration file
23 34845b8f 2022-01-23 op 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:
26 34845b8f 2022-01-23 op pki localhost cert "/etc/ssl/localhost.crt"
27 34845b8f 2022-01-23 op pki localhost key "/etc/ssl/private/localhost.key"
29 34845b8f 2022-01-23 op table users { "SHA256:..." => "op" }
31 34845b8f 2022-01-23 op listen on localhost port 1337 tls pki localhost auth <users>
34 34845b8f 2022-01-23 op "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.
36 5ed4e808 2022-01-30 op An easy way to generate certificates and obtain their fingerprint is by using the scripts ‘fingerprint’ and ‘gencert’ in the ‘contrib’ directory:
38 5ed4e808 2022-01-30 op ```example of how to use fingerprint and gencert
39 a3f21475 2022-02-09 op % ./contrib/gencert foo
40 5ed4e808 2022-01-30 op Generating a 4096 bit RSA private key
42 5ed4e808 2022-01-30 op writing new private key to 'foo'
44 a3f21475 2022-02-09 op % ./contrib/fingerprint foo
45 5ed4e808 2022-01-30 op SHA256:c043a39b4c65993f03b8df46116a692392399e3be0eb233f4efd74cd53540370
48 34845b8f 2022-01-23 op To check the configuration for syntax errors, execute:
55 34845b8f 2022-01-23 op ## 3. run the daemon
57 34845b8f 2022-01-23 op With all the previous steps done, running the daemon is as easy as:
63 34845b8f 2022-01-23 op use ‘-d’ to keep kamid in the foreground (i.e. not daemonize) and ‘-v’ to increase the verbosity.
65 34845b8f 2022-01-23 op Congratulations! Your kamid instance is up and running.
68 34845b8f 2022-01-23 op ## 4. connecting to the server
70 a1962ae7 2022-02-09 op 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’:
73 81d9a27f 2022-01-30 op $ kamiftp -C foo localhost
76 a1962ae7 2022-02-09 op (‘foo’ is the certificate previously generated)
78 34845b8f 2022-01-23 op 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!
80 34845b8f 2022-01-23 op => kamiftp.1.MANEXT kamiftp(1)
81 34845b8f 2022-01-23 op => https://notabug.org/cage/tinmop.git tinmop