Go C Other
Switch branches/tags
Clone or download
joshblum Merge pull request #1737 from keybase/joshblum/CORE-8530
Add NewlyAddedToTeam for NotifyTeamInterface
Latest commit 8e16aa7 Aug 14, 2018
Permalink
Failed to load latest commit information.
cache switch cache keytype from string to Measurable (#1337) Nov 15, 2017
dokan More verbose logging about the system upon mount failures with Dokan Jul 11, 2018
env kbfsfuse: get mountdir from config file if not specified Jan 25, 2018
fsrpc tlf_handle_resolve: use the team suffix when checking canonicals Mar 22, 2018
genprotocol kbgitkbfs: Rename protocol to kbgitkbfs1. Oct 30, 2017
ioutil ioutil: add WriteSerializeFile helper function Jun 27, 2017
kbfsblock kbfsblock: allow writer to be empty in json Aug 2, 2018
kbfscodec ioutil: add WriteSerializeFile helper function Jun 27, 2017
kbfscrypto kbfscrypto: fix merkle leaf comments and return values May 24, 2018
kbfsdokan Don't default to force mount in production for kbfsdokan (#1185) Sep 20, 2017
kbfsedits kbfsedits: ignore more macOS filenames Jul 5, 2018
kbfsfuse kbfsfuse: get mountdir from config file if not specified Jan 25, 2018
kbfsgit libfs: expose branch name parameter Jul 26, 2018
kbfshash switch cache keytype from string to Measurable (#1337) Nov 15, 2017
kbfsmd kbfsmd: new server error for a missing folder handle Aug 3, 2018
kbfssync disk_limiter: PR feedback by strib. Jul 14, 2017
kbfstool kbfstool: adapt to revoked key info change Apr 18, 2018
kbpagesconfig address rest of feedback from strib May 21, 2018
kbpagesd kbpagesd: use new way to specify protocols in params Jun 8, 2018
libdokan libfuse/libdokan: fix archive_reltime_file comment Jul 28, 2018
libfs libfs: return ErrNotExist if a non-final path element exists but is n… Aug 8, 2018
libfuse libfuse/libdokan: fix archive_reltime_file comment Jul 28, 2018
libgit libfs: expose branch name parameter Jul 26, 2018
libhttpserver libfs: expose branch name parameter Jul 26, 2018
libkbfs Add NewlyAddedToTeam for NotifyTeamInterface Aug 14, 2018
libmime review feedback from strib May 15, 2018
libpages libfs: expose branch name parameter Jul 26, 2018
metricsutil Add copyright to every Go file without one yet May 26, 2016
packaging/linux/systemd systemd: use the new keybase config bare mode when retrieving mountpoint Jul 12, 2018
protocol/kbgitkbfs1 kbgitkbfs: Rename protocol to kbgitkbfs1. Oct 30, 2017
redirector redirector: redirect /keybase/.kbfs_edit_history Jun 27, 2018
simplefs add filter to SimpleFSSyncStatus (#1721) Aug 8, 2018
stderrutils make stderr go to console again Jan 16, 2018
sysutils sysutils: compile on FreeBSD/amd64 May 25, 2017
test test: force dokan root dirs to not have symlinks Aug 3, 2018
tlf tlf: remove MarshalJSON in favor of the existing MarshalText Jun 2, 2018
vendor client master hashes Aug 14, 2018
.gitignore move libhttpserver initialization into SimpleFS (suggested by strib) May 2, 2018
Dockerfile allow setting server addrs for the GRH and GitHandler; Dockerfile cha… Oct 5, 2017
Jenkinsfile add gomock and mockgen to jenkinsfile Jun 25, 2018
LICENSE Update License year Jan 8, 2018
Makefile Actually fix lint checker Jun 14, 2018
README.md README: mention FreeBSD support. May 14, 2018
appveyor.yml fix appveyor go version Jun 25, 2018
circle.yml Use custom Docker image for CircleCI (#1729) Aug 9, 2018
docker-compose.yml Try to fix gregor Oct 28, 2016

README.md

Keybase Filesystem (KBFS) Build Status Build status

This repository contains the official Keybase implementation of the client-side code for the Keybase filesystem (KBFS). See the KBFS documentation for an introduction and overview.

Sharing

All code is written in the Go Language, and relies on the Keybase service.

Architecture

This client allows you to mount KBFS as a proper filesystem at some mountpoint on your local device (by default, /keybase/). It communicates locally with the Keybase service, and remotely with three types of KBFS servers (block servers, metadata servers, and key servers).

The code is organized as follows:

  • dokan: Helper code for running Dokan filesystems on Windows.
  • env: Code to implement libkbfs.Context in terms of libkb.
  • fsrpc: RPC interfaces that connected clients can call in KBFS, to do certain operations, such as listing files.
  • ioutil: Helper functions for I/O.
  • kbfsblock: Types and functions to work with KBFS blocks.
  • kbfscodec: Interfaces and types used for serialization in KBFS.
  • kbfscrypto: KBFS-specific cryptographic types and functions.
  • kbfsdokan: The main executable for running KBFS on Windows.
  • kbfsfuse: The main executable for running KBFS on Linux and OS X.
  • kbfshash: An implementation of the KBFS hash spec.
  • kbfsmd: Types and functions to work with KBFS TLF metadata.
  • kbfssync: KBFS-specific synchronization primitives.
  • kbfstool: A thin command line utility for interacting with KBFS without using a filesystem mountpoint.
  • libdokan: Library code gluing together KBFS and the Dokan protocol.
  • libfs: Common library code useful to any filesystem presentation layer for KBFS.
  • libfuse: Library code gluing together KBFS and the FUSE protocol.
  • libkbfs: The core logic for KBFS.
  • metricsutil: Helper code for collecting metrics.
  • test: A test harness with a domain-specific test language and tests in that language.
  • tlf: Code and structures for top-level folders (TLFs).
  • vendor: Vendored versions of the open-source libraries used by KBFS.

Status

KBFS currently works on both Linux (at least Debian, Ubuntu and Arch), OS X, and Windows. It is approaching release ready, though currently it is still in alpha. There may still be bugs, so please keep backups of any important data you store in KBFS. Currently our pre-built packages are available by invitation only.

KBFS depends in part on the following awesome technologies to present a mountpoint on your device:

See our vendor directory for a complete list of open source packages KBFS uses.

Currently, our server implementations are not open source.

To run from source against production KBFS servers

On Linux or OS X:

Prerequisites:

  • Go 1.7 or higher.
  • A running Keybase client service (see instructions).
  • On OS X, you may have to install FUSE yourself.
    • You may need to pass the --use-system-fuse flag to kbfsfuse if you install FUSE yourself.
  • Then, mount KBFS at /keybase/ as follows:
    cd kbfsfuse
    go install
    mkdir -p /keybase && sudo chown $USER /keybase
    KEYBASE_RUN_MODE=prod kbfsfuse /keybase

Note that our pre-built packages for OS X include a branded version of FUSE for OS X, to ensure that it doesn't conflict with other local FUSE installations. It is still open source -- see here to see how we build it.

On Windows:

See our kbfsdokan documentation.

On FreeBSD:

There are instructions for getting KBFS running on FreeBSD here. This is a user-supported effort, which is not officially supported by the Keybase team at the moment.

To run from source against local in-memory servers

kbfsfuse -bserver=memory -mdserver=memory -localuser strib /keybase

(Use -bserver=dir:/path/to/dir and -mdserver=dir:/path/to/dir if instead you want to save your data to local disk.)

Now you can do cool stuff like:

ls /keybase/private/strib
echo blahblah > /keybase/private/strib/foo
ls /keybase/private/strib,max

(Note that "localuser" mode has only four hard-coded users to play with: "strib", "max", "chris", and "fred".)

Code style

We require all code to pass gofmt and govet. You can install our precommit hooks to make sure your code passes gofmt and govet:

go get golang.org/x/tools/cmd/vet
ln -s $GOPATH/src/github.com/keybase/client/git-hooks/pre-commit $GOPATH/src/github.com/keybase/kbfs/.git/hooks/pre-commit

Though it doesn't happen automatically, we also expect your code to be as "lint-free" as possible. Running golint is easy from the top-level kbfs directory:

go get -u github.com/golang/lint/golint
make lint

Vendoring

KBFS vendors all of its dependencies into the local vendor directory. To add or update dependencies, use the govendor tool, as follows:

go install github.com/kardianos/govendor
govendor add github.com/foo/bar  # or `govendor update`
git add --all vendor

Testing

From kbfs/:

go test -i ./...
go test ./...

If you change anything in interfaces.go, you will have to regenerate the mock interfaces used by the tests:

cd libkbfs
./gen_mocks.sh

(Right now the mocks are checked into the repo; this isn't ideal and we should probably change it.)

Licensing

Most code is released under the New BSD (3 Clause) License. If subdirectories include a different license, that license applies instead. (Specifically, dokan/dokan_header and most subdirectories in vendor are released under their own licenses.)