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 34845b8f 2022-01-23 op kamid needs a dedicated ‘_kamid’ user to run.  How to create an user depends on your operating system; 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 34845b8f 2022-01-23 op or on some GNU/linux systems:
12 34845b8f 2022-01-23 op 
13 34845b8f 2022-01-23 op ```
14 34845b8f 2022-01-23 op # useradd --system --no-create-home -s /bin/nologin -c kamid _kamid
15 34845b8f 2022-01-23 op ```
16 34845b8f 2022-01-23 op 
17 34845b8f 2022-01-23 op Ideally the ‘_kamid’ user shouldn’t have a login shell and have an empty home.
18 34845b8f 2022-01-23 op 
19 34845b8f 2022-01-23 op 
20 34845b8f 2022-01-23 op ## 2. create a configuration file
21 34845b8f 2022-01-23 op 
22 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:
23 34845b8f 2022-01-23 op 
24 34845b8f 2022-01-23 op ```
25 34845b8f 2022-01-23 op pki localhost cert "/etc/ssl/localhost.crt"
26 34845b8f 2022-01-23 op pki localhost key "/etc/ssl/private/localhost.key"
27 34845b8f 2022-01-23 op 
28 34845b8f 2022-01-23 op table users { "SHA256:..." => "op" }
29 34845b8f 2022-01-23 op 
30 34845b8f 2022-01-23 op listen on localhost port 1337 tls pki localhost auth <users>
31 34845b8f 2022-01-23 op ```
32 34845b8f 2022-01-23 op 
33 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.
34 34845b8f 2022-01-23 op 
35 34845b8f 2022-01-23 op To check the configuration for syntax errors, execute:
36 34845b8f 2022-01-23 op 
37 34845b8f 2022-01-23 op ```
38 34845b8f 2022-01-23 op $ kamid -n
39 34845b8f 2022-01-23 op ```
40 34845b8f 2022-01-23 op 
41 34845b8f 2022-01-23 op 
42 34845b8f 2022-01-23 op ## 3. run the daemon
43 34845b8f 2022-01-23 op 
44 34845b8f 2022-01-23 op With all the previous steps done, running the daemon is as easy as:
45 34845b8f 2022-01-23 op 
46 34845b8f 2022-01-23 op ```
47 34845b8f 2022-01-23 op # kamid
48 34845b8f 2022-01-23 op ```
49 34845b8f 2022-01-23 op 
50 34845b8f 2022-01-23 op use ‘-d’ to keep kamid in the foreground (i.e. not daemonize) and ‘-v’ to increase the verbosity.
51 34845b8f 2022-01-23 op 
52 34845b8f 2022-01-23 op Congratulations!  Your kamid instance is up and running.
53 34845b8f 2022-01-23 op 
54 34845b8f 2022-01-23 op 
55 34845b8f 2022-01-23 op ## 4. connecting to the server
56 34845b8f 2022-01-23 op 
57 34845b8f 2022-01-23 op There are quite a few clients for 9p, even if not all may support 9p over TLS.  As part of kamid there is a small ftp(1)-like client called ‘kamiftp’:
58 34845b8f 2022-01-23 op 
59 34845b8f 2022-01-23 op ```
60 34845b8f 2022-01-23 op $ kamiftp -c -C client.pem -K client.key localhost
61 34845b8f 2022-01-23 op ```
62 34845b8f 2022-01-23 op 
63 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!
64 34845b8f 2022-01-23 op 
65 34845b8f 2022-01-23 op => kamiftp.1.MANEXT			kamiftp(1)
66 34845b8f 2022-01-23 op => https://notabug.org/cage/tinmop.git	tinmop