kbfsd.5

.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2018-2021 Mateusz Piotrowski <0mp@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.Dd July 22, 2021
.Dt KBFSD 5
.Os
.Sh NAME
.Nm kbfsd
.Nd service daemon for the Keybase filesystem (KBFS)
.Sh SYNOPSIS
Required
.Xr rc.conf 5
variables:
.Bd -literal -offset indent
kbfsd_enable="YES"
kbfsd_user="beastie"
.Ed
.Pp
Optional
.Xr rc.conf 5
variables:
.Bd -literal -offset indent
kbfsd_keybase_username="${kbfsd_user}"
kbfsd_mountpoint="/keybase"
.Ed
.Sh DESCRIPTION
.Nm
is an
.Xr rc 8
daemon for the Keybase filesystem (KBFS).
Its aim is to ease the process of using KBFS on
.Fx .
It takes care of the configuration the Keybase user would have to do manually
otherwise.
.Pp
.Nm
does not start automatically even when
.Va kbfsd_enable
is set to
.Ql YES
in
.Xr rc.conf 5 .
See the
.Sx CAVEATS
section for more details.
.Pp
.Nm
has to configure some bits of the system in order to mount KBFS as
.Va kbfsd_user .
.Va kbfsd_mountpoint
is created and
the
.Xr sysctl 8
tunable
.Va vfs.usermount
is set to
.Dq 1
so that
.Va kbfsd_user
could mount
.Va kbfsd_mountpoint .
Then
.Va kbfsd_user
is added to the
.Dq operator
group to be able to use the
.Pa /dev/fuse
device.
Finally,
.Nm
attempts to spin off the Keybase server and create required socket files.
Note that this step requires
.Va kbfsd_user
to be able to log in as
.Va kbfsd_keybase_username .
This should be possible once
.Va kbfsd_user
registers a device with
.Ql keybase device add .
.Pp
.Nm
may be controlled with the following
.Xr rc.conf 5
variables:
.Bl -tag -width kbfsd_keybase_username
.It Va kbfsd_enable
.Pq Vt bool , No default: Ql NO
Enable
.Nm .
.It Va kbfsd_keybase_username
.Pq Vt str , No default: Va kbfsd_user
The username used to log into Keybase.
.It Va kbfsd_mountpoint
.Pq Vt str , No default: Ql /keybase
The directory where KBFS should be mounted.
.It Va kbfsd_user
.Pq Vt str , No no defaults
The login name of a user, who should own
.Va kbfsd_mountpoint .
It cannot be empty.
.El
.Sh INSTALLATION
The easiest way is to just install the
.Nm
package via
.Xr pkg 8
on
.Fx :
.Bd -literal -offset indent
pkg install kbfsd
.Ed
.Pp
.Nm
can be installed manually with the following command:
.Bd -literal -offset indent
make all
make install
.Ed
.Sh FILES
.Bl -tag -width "/home/${kbfsd_user}/.config/keybase/kbfsd.${kbfsd_user}.pid" -compact
.Sm off
.It Pa /home/ No ${ Ar kbfsd_user No } Pa /.config/keybase/kbfsd\&. No ${ Ar kbfsd_user No } Pa ".pid"
.Sm on
PID file.
.El
.Sh EXIT STATUS
The
.Nm
daemon
exits 0 on success, and >0 if an error occurs.
.Sh SEE ALSO
.Xr rc.conf 5 ,
.Xr mount 8 ,
.Xr rc 8
.Sh AUTHORS
The
.Nm
daemon and its manual page were written by
.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
.Sh CAVEATS
.Nm
is
.Em not
started automatically together with other daemons during boot because it uses
the
.Ql nostart
KEYWORD
.Pq see Xr rc 8 for details .
The reason is that in order to reliably mount KBFS the user has to establish
a session with the Keybase server first.
This is done by calling:
.Ql keybase login username
.Po where
.Ar username
is the same as
.Ar kbfsd_keybase_username
.Pc .
Unfortunately, this command happens to block the booting process from time to
time, which is unacceptable.
.Sh BUGS
.Nm
seems to kill
.Nm kbfsfuse
too rapidly for
.Nm kbfsfuse
to properly unmount.
As a workaround,
.Nm
calls
.Xr umount 8
on the mount point in the
.Em poststop
phase
.Pq see Xr rc.subr 8 .
.Pp
Currently,
.Nm
uses
.Va kbfsd_env
internally to set the
.Ev HOME
environmental variable to the home directory of
.Va kbfsd_user .
It is recommended to read the service file before setting
.Va kbfsd_env
in
.Xr rc.conf 5 .
.Pp
On some
.Fx
versions older than 13.0 the name of
.Xr fusefs 5
might be
.Dq fuse
instead of
.Dq fusefs .
As a result,
.Nm
might fail to start.
A potential workaronud is to set
.Va required_modules
to an empty string in
.Pa /usr/local/etc/rc.conf.d/kbfsd
and then loading the FUSE kernel module differently
.Po e.g., via
.Va kld_list
in
.Xr rc.conf 5
.Pc .