README.md
1
2
3# NAME
4
5**kbfsd** - service daemon for the Keybase filesystem (KBFS)
6
7# SYNOPSIS
8
9The required
10rc.conf(5)
11variables:
12
13*kbfsd\_enable*="`NO`"
14*kbfsd\_user*="*user*"
15
16Optional
17rc.conf(5)
18variables:
19
20*kbfsd\_keybase\_username*="`${`*kbfsd\_user*`}`"
21*kbfsd\_mountpoint*="*/keybase*"
22
23# DESCRIPTION
24
25**kbfsd**
26is an
27rc(8)
28daemon for the Keybase filesystem (KBFS).
29Its aim is to ease the process of using KBFS on
30FreeBSD.
31It takes care of the configuration the Keybase user would have to do manually
32otherwise.
33
34**kbfsd**
35does not start automatically even when
36*kbfsd\_enable*
37is set to
38"`YES`"
39in
40rc.conf(5).
41See the
42*CAVEATS*
43section for more details.
44
45**kbfsd**
46has to configure some bits of the system in order to mount KBFS as
47*kbfsd\_user*.
48*kbfsd\_mountpoint*
49is created and
50the
51sysctl(8)
52tunable
53*vfs.usermount*
54is set to
55"1"
56so that
57*kbfsd\_user*
58could mount
59*kbfsd\_mountpoint*.
60Then
61*kbfsd\_user*
62is added to the
63"operator"
64group to be able to use the
65*/dev/fuse*
66device.
67Finally,
68**kbfsd**
69attempts to spin off the Keybase server and create required socket files.
70Note that this step requires
71*kbfsd\_user*
72to be able to log in as
73*kbfsd\_keybase\_username*.
74This should be possible once
75*kbfsd\_user*
76registers a device with
77"`keybase device add`".
78
79**kbfsd**
80may be controlled with the following
81rc.conf(5)
82variables:
83
84*kbfsd\_enable*
85
86> (*bool*, default: "`NO`")
87> Enable
88> **kbfsd**.
89
90*kbfsd\_keybase\_username*
91
92> (*str*, default: *kbfsd\_user*)
93> The username used to log into Keybase.
94
95*kbfsd\_mountpoint*
96
97> (*str*, default: "`/keybase`")
98> The directory where KBFS should be mounted.
99
100*kbfsd\_user*
101
102> (*str*, no defaults)
103> The login name of a user, who should own
104> *kbfsd\_mountpoint*.
105> It cannot be empty.
106
107# INSTALLATION
108
109The easiest way is to just install the
110**kbfsd**
111package via
112pkg(8)
113on
114FreeBSD:
115
116 pkg install kbfsd
117
118**kbfsd**
119can be installed manually with the following command:
120
121 make all
122 make install
123
124# FILES
125
126*/home/*${*kbfsd\_user*}*/.config/keybase/kbfsd.*${*kbfsd\_user*}*.pid*
127
128> PID file.
129
130# EXIT STATUS
131
132The
133**kbfsd**
134daemon
135exits 0 on success, and >0 if an error occurs.
136
137# SEE ALSO
138
139rc.conf(5),
140mount(8),
141rc(8)
142
143# AUTHORS
144
145The
146**kbfsd**
147daemon and its manual page were written by
148Mateusz Piotrowski <[0mp@FreeBSD.org](mailto:0mp@FreeBSD.org)>.
149
150# CAVEATS
151
152**kbfsd**
153is
154*not*
155started automatically together with other daemons during boot because it uses
156the
157"`nostart`"
158KEYWORD
159(see rc(8) for details).
160The reason is that in order to reliably mount KBFS the user has to establish
161a session with the Keybase server first.
162This is done by calling:
163"`keybase login` *username*".
164Unfortunately, this command happens to block the booting process from time to
165time, which is unacceptable.
166
167# BUGS
168
169**kbfsd**
170seems to kill
171**kbfsfuse**
172too rapidly for
173**kbfsfuse**
174to properly unmount.
175As a workaround,
176**kbfsd**
177calls
178umount(8)
179on the mount point in the
180*poststop*
181phase
182(see rc.subr(8)).
183
184Currently,
185**kbfsd**
186uses
187*kbfsd\_env*
188internally to set the
189`HOME`
190environmental variable to the home directory of
191*kbfsd\_user*.
192It is recommended to read the service file before setting
193*kbfsd\_env*
194in
195rc.conf(5).
196