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