1 f6a3556c 2022-01-23 op # setup guide
 2 4c8aba72 2022-01-23 op 
 3 34845b8f 2022-01-23 op ## 1. create a dedicated user
 4 34845b8f 2022-01-23 op 
 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:
 6 34845b8f 2022-01-23 op 
 7 34845b8f 2022-01-23 op ```
 8 34845b8f 2022-01-23 op # useradd -c kamid -d /var/empty -s /sbin/nologin _kamid
 9 34845b8f 2022-01-23 op ```
10 34845b8f 2022-01-23 op 
11 a3f21475 2022-02-09 op while on some GNU/linux systems:
12 34845b8f 2022-01-23 op 
13 34845b8f 2022-01-23 op ```
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
16 34845b8f 2022-01-23 op ```
17 34845b8f 2022-01-23 op 
18 34845b8f 2022-01-23 op Ideally the ‘_kamid’ user shouldn’t have a login shell and have an empty home.
19 34845b8f 2022-01-23 op 
20 34845b8f 2022-01-23 op 
21 34845b8f 2022-01-23 op ## 2. create a configuration file
22 34845b8f 2022-01-23 op 
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:
24 34845b8f 2022-01-23 op 
25 34845b8f 2022-01-23 op ```
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"
28 34845b8f 2022-01-23 op 
29 34845b8f 2022-01-23 op table users { "SHA256:..." => "op" }
30 34845b8f 2022-01-23 op 
31 34845b8f 2022-01-23 op listen on localhost port 1337 tls pki localhost auth <users>
32 34845b8f 2022-01-23 op ```
33 34845b8f 2022-01-23 op 
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.
35 34845b8f 2022-01-23 op 
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:
37 5ed4e808 2022-01-30 op 
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
41 5ed4e808 2022-01-30 op [...]
42 5ed4e808 2022-01-30 op writing new private key to 'foo'
43 5ed4e808 2022-01-30 op -----
44 a3f21475 2022-02-09 op % ./contrib/fingerprint foo
45 5ed4e808 2022-01-30 op SHA256:c043a39b4c65993f03b8df46116a692392399e3be0eb233f4efd74cd53540370
46 5ed4e808 2022-01-30 op ```
47 5ed4e808 2022-01-30 op 
48 34845b8f 2022-01-23 op To check the configuration for syntax errors, execute:
49 34845b8f 2022-01-23 op 
50 34845b8f 2022-01-23 op ```
51 34845b8f 2022-01-23 op $ kamid -n
52 34845b8f 2022-01-23 op ```
53 34845b8f 2022-01-23 op 
54 34845b8f 2022-01-23 op 
55 34845b8f 2022-01-23 op ## 3. run the daemon
56 34845b8f 2022-01-23 op 
57 34845b8f 2022-01-23 op With all the previous steps done, running the daemon is as easy as:
58 34845b8f 2022-01-23 op 
59 34845b8f 2022-01-23 op ```
60 34845b8f 2022-01-23 op # kamid
61 34845b8f 2022-01-23 op ```
62 34845b8f 2022-01-23 op 
63 34845b8f 2022-01-23 op use ‘-d’ to keep kamid in the foreground (i.e. not daemonize) and ‘-v’ to increase the verbosity.
64 34845b8f 2022-01-23 op 
65 34845b8f 2022-01-23 op Congratulations!  Your kamid instance is up and running.
66 34845b8f 2022-01-23 op 
67 34845b8f 2022-01-23 op 
68 34845b8f 2022-01-23 op ## 4. connecting to the server
69 34845b8f 2022-01-23 op 
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’:
71 34845b8f 2022-01-23 op 
72 34845b8f 2022-01-23 op ```
73 81d9a27f 2022-01-30 op $ kamiftp -C foo localhost
74 34845b8f 2022-01-23 op ```
75 34845b8f 2022-01-23 op 
76 a1962ae7 2022-02-09 op (‘foo’ is the certificate previously generated)
77 81d9a27f 2022-01-30 op 
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!
79 34845b8f 2022-01-23 op 
80 34845b8f 2022-01-23 op => kamiftp.1.MANEXT			kamiftp(1)
81 34845b8f 2022-01-23 op => https://notabug.org/cage/tinmop.git	tinmop