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 An easy way to generate certificates and obtain their fingerprint is by using the scripts ‘fingerprint’ and ‘gencert’ in the ‘contrib’ directory:
36 
37 ```example of how to use fingerprint and gencert
38 % ./gencert foo
39 Generating a 4096 bit RSA private key
40 [...]
41 writing new private key to 'foo'
42 -----
43 % ./fingerprint foo
44 SHA256:c043a39b4c65993f03b8df46116a692392399e3be0eb233f4efd74cd53540370
45 ```
46 
47 To check the configuration for syntax errors, execute:
48 
49 ```
50 $ kamid -n
51 ```
52 
53 
54 ## 3. run the daemon
55 
56 With all the previous steps done, running the daemon is as easy as:
57 
58 ```
59 # kamid
60 ```
61 
62 use ‘-d’ to keep kamid in the foreground (i.e. not daemonize) and ‘-v’ to increase the verbosity.
63 
64 Congratulations!  Your kamid instance is up and running.
65 
66 
67 ## 4. connecting to the server
68 
69 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’:
70 
71 ```
72 $ kamiftp -C foo localhost
73 ```
74 
75 (‘foo’ is the certificate generated previously)
76 
77 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!
78 
79 => kamiftp.1.MANEXT			kamiftp(1)
80 => https://notabug.org/cage/tinmop.git	tinmop