Linux User Guide

Welcome to the Keybase Linux User Guide!

This guide is intended for everyone from Linux beginners to experts to distribution package maintainers. It covers some topics that are unique to Keybase on Linux. If you have any feedback or questions, let us know!

1. Quickstart
2. Example Commands
3. Nightly Builds
4. Autostart
5. run_keybase
6. systemd and running headless Keybase
7. Example: Daily KBFS backup on a systemd timer
8. Configuring KBFS
9. Installing Keybase without Root Privileges
10. For Package Maintainers
11. Feedback and Questions

Quickstart

Keybase officially supports only Ubuntu, Debian, Fedora, CentOS, and Arch, but there are other packages for other systems as well.

Note that the packages maintained by us are the quickest to get the latest features and security updates, the community packages may have packaging issues beyond our control, and the instructions below may not work out of the box.

No matter how you install, you should get updates automatically by running your package manager's update command.

If you installed Keybase via an official package, you should have the script run_keybase available, which starts up Keybase, KBFS, and the GUI.

run_keybase
...
success!

Now that Keybase is running, you'll be able to create an account or log into the GUI. Once logged in, you can make proofs, chat with friends, browse your KBFS files all in the GUI.

Example Commands

The following aren't specific to Linux, but demonstrate many of Keybase's features.

keybase signup # create an account
keybase id # print your username and proofs
keybase prove twitter # prove your twitter identity
keybase prove -l # list available proof types
keybase id {some-keybase-username} # check proofs of another user
keybase chat send {some-keybase-username} -m "Hey! I'm on Keybase now!" # send an encrypted message

# see if this github user is on Keybase
keybase id {some-github-username}@github

# send a (encrypted) message to a twitter user, *even if they aren't on Keybase
# yet* (they'll get the message when they join)
keybase chat send {some-reddit-username}@reddit -m "Hey! I'm on Keybase now!"

# encrypt a file or message for another keybase user to send over an unsecure
# chat channel
keybase encrypt {some-keybase-username} -m "hello, world"
BEGIN KEYBASE SALTPACK ENCRYPTED MESSAGE. kigG6zVjgVFCFLm GxarUYJUY9RGEoH ... e6lZF0EDl3VFSI4 jE0rHiCLJGYpSwk l1ohzskP1Myn9lz . END KEYBASE SALTPACK ENCRYPTED MESSAGE.

# Start a "one shot" temporary device with a paperkey, useful, e.g.,
# for logging onto Keybase in a Docker container
keybase oneshot --help

keybase help # see all available commands

With KBFS running, you'll be able to add files to the magic /keybase directory. Everything in this directory is encrypted on your machine and synced with all your devices. No one else, including Keybase, has access to your files unless you choose to make them public or share them with other users. More information is available at Understanding KBFS.

# Add a public file for anyone on Keybase to view
echo "hello, world" > /keybase/public/{your-username}/hello.txt

# Add a private file encrypted only for yourself
cp ~/documents/taxes.pdf /keybase/private/{your-username}/taxes.pdf

# Add a private file encrypted only for yourself and the owner of some website,
# *even if they haven't joined keybase yet* (they'll get it when they join and
# prove that they own that website)
cp ~/documents/proposal.pdf /keybase/private/{your-username},example.com@https/proposal.pdf

# Add a file shared privately between a group of people
cp ~/documents/resume.pdf /keybase/private/{your-username},{some-keybase-username}/resume.pdf

# Add a file shared privately to a Keybase team
mkdir /keybase/team/{your-team-name}/devops/backups/
mv ~/backups/database.tar.gz /keybase/team/{your-team-name}/devops/backups/database.tar.gz

# Create an private encrypted git repository synced between your devices
# See also: https://keybase.io/blog/encrypted-git-for-everyone
keybase git create my-project

# Interact with KBFS without a mount
# Useful, e.g., in systems like ChromiumOS that may not provide FUSE
keybase fs ls /keybase/team/

If you're using a package that doesn't provide the keybase redirector, /keybase may not exist. In that case, your folder is available at the location given by keybase config get -b mountdir (more on that later).

If you're looking for people to talk to, head on over to our Popular Teams page and request to join a public team from within the GUI (or with keybase team request-access). keybasefriends, in particular, is a great place to start for general discussion and questions about Keybase. More information on teams is available here and here.

And that's it! There's plenty of more features to play around with in the app and in the command line.

You don't need to go any farther than this if you just want to use Keybase, but the below sections detail advanced topics for users who want to have more knowledge and control over how Keybase runs on their system.

Nightly Builds

We now offer .deb, .rpm, and Arch nightly builds!

Standard disclaimer: these are not official releases and may cause unexpected crashes and instability. Use with caution.

Note that we are not providing package repositories for .deb and .rpm nightlies (yet): you'll need to manually dpkg -i or rpm -i to install and update to the next nightly instead of using apt-get or yum. However, if you're on Arch, you can update by just reinstalling keybase-git.

To enable experimental GUI features, create a debug file:

$ cat ~/.cache/keybase/keybase.app.debug # or in your $XDG_CACHE_HOME/keybase
{ "featureFlagsOverride": "admin" }

Of course, this won't give you any additional access permissions and some of these features may be server-gated as well, so they may not work correctly or at all.

If you find any bugs or issues with these nightly builds, please report them and we'll do our best to get a fix out soon! Specify [NIGHTLY] in the issue title as well.

Autostart

If you're using a graphical desktop environment like KDE or Gnome, Keybase installs a autostart desktop file into ~/.config/autostart/keybase_autostart.desktop. If you don't want this behavior, you can disable it in your desktop environment settings, or run

keybase ctl autostart --disable

If you're on a headless system, you probably want to use the systemd units instead. If you're using a window manager like i3wm, you can just have it execute run_keybase on startup. If you want Keybase to start but don't want the GUI to be maximized, change the command to run_keybase -a. You'll be able to open the GUI from the icon in the system tray.

When using systemctl to start the GUI, you must import KEYBASE_AUTOSTART=1 into the environment for the gui to start but stay in the background. The unit file unsets this variable right after so subsequent calls will start it maximized, unless that variable has been set again:

systemctl --user set-environment KEYBASE_AUTOSTART=1

run_keybase

run_keybase accepts some more options for controlling Keybase.

$ run_keybase -h
Starts the Keybase service, KBFS, and the GUI.
If services are already running, they will be restarted.

Options can also be controlled by setting related environment variables to 1
  -a  keep the GUI minimized in system tray after startup (env KEYBASE_AUTOSTART=1)
  -f  do not start KBFS (env KEYBASE_NO_KBFS=1)
  -g  do not start the gui (env KEYBASE_NO_GUI=1)
  -h  print this help text
  -k  shut down all Keybase services (env KEYBASE_KILL=1)

When run_keybase is executed, up to four background processes start: keybase, kbfsfuse, Keybase, and keybase-redirector.

• keybase is the main service that powers all other Keybase operations, and also provides the command line tool. You can use keybase by itself if you prefer.

• kbfsfuse allows you to use KBFS and KBFS git, and depends on keybase.

• Keybase is the GUI app, and depends on keybase and kbfsfuse.

• keybase-redirector provides the magic /keybase KBFS directory, but isn't required for using KBFS.

run_keybase tries to run its processes as systemd user manager services if your system supports it (Arch, Ubuntu, Debian), but if can't, it falls back to starting regular background processes.

You can see if you're running via systemd with

systemctl --user status keybase keybase.gui kbfs keybase-redirector
# (if you don't have that command, you aren't using systemd)

If you don't want to start a background process, you can try

keybase --standalone {rest-of-command}

but this mode is not supported for all Keybase features (e.g., chat), and will likely be slower.

systemd and running headless Keybase

If you're running Keybase on a server, you may want finer-grained control over Keybase than run_keybase provides. In this case, you can to configure the systemd units directly without using run_keybase.

Note that keybase cannot be run as root, and must be run as a user. Accordingly, it runs under the system user manager of a particular user, not the global system manager.

First, perform some basic environment setup required for the systemd units.

keybase ctl init

Among other things, this forwards a few environment variables to the systemd units. If they ever change, you'll need to run this command (or run_keybase) again to refresh them. Because systemd units do not automatically forward the user environment, this cannot be run automatically in the ExecStartPre directive. However, you could choose to have it run on login in a shell profile or rc file. Specifically, this creates a file at ~/.config/keybase/keybase.autogen.env (or in your $XDG_CONFIG_HOME). Environment variables can be overridden by writing to keybase.env in the same directory, or by creating a systemctl drop-in configuration with Environment directives.

Optionally enable units to autostart on system boot. You can choose a subset of these, but remember that KBFS depends on Keybase (and will start it if it isn't already up).

systemctl --user enable keybase.service
systemctl --user enable kbfs.service
systemctl --user enable keybase-redirector.service

Optionally allow Keybase to keep running even if you're logged out. If you've SSHed into a server, you can do this so Keybase and KBFS keep working after your session ends.

loginctl enable-linger

Next, start up Keybase services.

systemctl --user start keybase.service
systemctl --user start kbfs.service
systemctl --user start keybase-redirector.service

Now, you should be able to use KBFS and use Keybase from the command line.

keybase id

If you ran into a issue, you can restart services with

systemctl --user restart keybase kbfs keybase-redirector

Note that the GUI also runs as a systemd unit.

systemctl --user start keybase.gui

For this to work, you must have your $DISPLAY configured in the environmentfile, which should already be the case if you configured your environmentfile as directed above or executed run_keybase in the session. Of course, it won't work in a ssh session unless you've configured X forwarding.

If you ever need to edit the systemd units, run

systemctl --user edit {unit-name}

and you'll be able to individually override directives in a drop-in directory. If you run into issues after an upgrade, you may need to merge in changes from the upstream unit file, so only do this as a last resort.

Finally, if you don't want run_keybase to use systemd, you can export KEYBASE_SYSTEMD=0 and it will fall back to starting background processes. It does this automatically if it detects that the systemd user manager is not supported on your system.

Example: Daily KBFS backup on a systemd timer

Now that you know the basics, let's see how you could run Keybase on a server making a daily backup to KBFS (again, encrypted and automatically synced to all your other Keybase devices, or even a group of users or a team!).

Instead of a systemd timer, you could also choose to write a cronjob. Just make sure it runs as your user cronjob and if not using systemd, execute run_keybase first so Keybase services start up before you start your script.

Remember that your KBFS quota, given by keybase fs quota, is currently 250GB.

Follow the instructions in the previous section. Now, create a systemd unit that does a backup once. It might look like this:

$ cat ~/.config/systemd/user/kbfs-backup.service
[Unit]
Requires=keybase.service kbfs.service keybase-redirector.service
Description=make a backup of my photos

[Service]
ExecStart=%h/scripts/run-kbfs-backup

$ cat ~/scripts/run-kbfs-backup
#!/bin/bash
set -euo pipefail

function date {
    date --utc +%Y%m%d_%H%M%SZ
}

keybase_username={your-keybase-username}
archive="backup-$(date).tar.gz"
tar -czvf "$HOME/$archive" "$HOME/photos"
mkdir -p "/keybase/private/$keybase_username/backups/"
mv "$HOME/$archive" "/keybase/private/$keybase_username/backups/$archive"

$ chmod +x ~/scripts/run-kbfs-backup

Of course, you can improve upon this simple example with tools like rsync.

Finally, create a timer file. It might look like this:

$ cat ~/.config/systemd/user/kbfs-backup.timer
[Unit]
Description=run kbfs-backup.service every weekday at noon

[Timer]
OnCalendar=Mon-Fri 12:00
Persistent=true

[Install]
WantedBy=timers.target

$ systemctl --user enable --now kbfs-backup.timer

You're done! You can inspect the logs of your timer and check for failures with journalctl --user.

To run a backup once manually, just do

systemctl --user start kbfs-backup.timer

Configuring KBFS

For more information about how KBFS works, you can read Understanding KBFS.

On Linux, kbfsfuse mounts a FUSE filesystem to a directory the user running Keybase owns. Then, keybase-redirector mounts at /keybase, and shows a different version of /keybase depending on which user is asking for KBFS data.

If $XDG_RUNTIME_USER is configured (usually by systemd), this mountdir is at $XDG_RUNTIME_USER/keybase/kbfs/, or otherwise, at ~/.config/keybase/kbfs. Additionally, your package maintainer may have preconfigured this to be somewhere else.

To see your current mountdir, run

keybase config get -b mountdir

You can change it by running

keybase config set mountdir ~/another-mount-dir
run_keybase # or restart systemd services

Make sure nothing is using KBFS before you restart services. Also, be wary of setting the mountdir to somewhere within your home directory, for fear of tools like find or grep accidentally crawling KBFS.

Finally, you may want to disable the redirector. This is an administrator command: it requires root privileges.

You can do this with

sudo keybase --use-root-config-file ctl redirector --disable

or turn it back on with

sudo keybase --use-root-config-file ctl redirector --enable

Again, make sure KBFS is not being used before you run these commands. An enabled redirector is owned by root and has the setuid bit set. When you disable it, that bit is unset, and users will be unable to access /keybase or run the redirector. For convenience, users can include something like

export keybase="$(keybase config get --direct --bare mountdir)"

in their shell profile or rc file so they can access their files at $keybase/private/<their-username>, etc.

Installing Keybase without Root Privileges

Keybase uses root privileges only for making the magic /keybase directory available.

If you want to install Keybase without root privileges, you can, for example, unpack the .deb file and run the binaries out of there. If you put the binaries in your $PATH, you can even symlink the provided systemd unit files to your ~/.config/systemd/user directory and use the systemd user manager to manage your custom Keybase install. Note that the KBFS mount will not be accessible at /keybase, but at the user-writable mountdir (see Configuring KBFS).

Alternatively, you can choose to build Keybase from source for full customization over your install, as described in For Package Maintainers.

For Package Maintainers

We're glad that you're interested in packaging Keybase! There are a lot of moving parts involved, so packaging can get tricky.

Our scripts are available at https://github.com/keybase/client/tree/master/packaging/linux.

Of particular note are post_install.sh, and run_keybase. You don't have to package these, but you should include the necessary configuration and documentation so users are able to use Keybase.

Our code signing fingerprint is in the same directory at code_signing_fingerprint and available on our website.

You can also extract the binaries we build ourselves from the .deb files in our release directory instead of building from source. You may choose to package Keybase, KBFS, and the GUI all together or in separate packages, but make sure the dependencies are specified.

Let us know if you've created a package and want to be added to the list at the top of this page. In particular, init scripts for SysVinit and OpenRC may be of interest to other package maintainers.

Feedback and Questions

We aim to make Keybase flexible for everyone to use from desktop users to server admins.

If you believe you've found a security issue or a bug, see our bug reporting page. Please do a keybase log send from the command line when filing a bug report so developers can help you faster.

If you have a feature request, you can make a GitHub issue or join the keybasefriends team on Keybase and post in the #feature-requests channel. Or if you just need general help, post in the #general channel.