Installing Tahoe-LAFS — Tahoe-LAFS 1.x documentation

Installing Tahoe-LAFS¶
Welcome to the Tahoe-LAFS project, a secure, decentralized, fault-tolerant
storage system. See Welcome to Tahoe-LAFS! for an overview of the architecture and
security properties of the system.
This procedure should work on Windows, Mac, illumos (previously OpenSolaris),
and too many flavors of Linux and of BSD to list.

First: In Case Of Trouble¶
In some cases these instructions may fail due to peculiarities of your
platform.
If the following instructions don’t Just Work without any further effort on
your part, then please write to the tahoe-dev mailing list where friendly
hackers will help you out.

Pre-Packaged Versions¶
You may not need to build Tahoe at all.
If you are on Windows, please see Building Tahoe-LAFS on Windows for platform-specific
instructions.
If you are on a Mac, you can either follow these instructions, or use the
pre-packaged bundle described in OS-X Packaging.
Many Linux distributions include Tahoe-LAFS packages. Debian and Ubuntu users
can apt-get install tahoe-lafs. See OSPackages for other
platforms.

Preliminaries¶
If you don’t use a pre-packaged copy of Tahoe, you can build it yourself.
You’ll need Python2.7, pip, and virtualenv.
Tahoe-LAFS depends on some libraries which require a C compiler to build.
However, for many platforms, PyPI hosts already-built packages of libraries.
If there is no already-built package for your platform,
you will need a C compiler,
the Python development headers,
and some libraries (libffi-dev and libssl-dev).
On a modern Debian/Ubuntu-derived distribution, this command will get you
everything you need:
apt-get install build-essential python-dev libffi-dev libssl-dev libyaml-dev python-virtualenv

On OS-X, install pip and virtualenv as described below. If you want to
compile the dependencies yourself, you’ll also need to install
Xcode and its command-line tools.
Note that Tahoe-LAFS depends on openssl 1.1.1c or greater.

Python 2.7¶
Check if you already have an adequate version of Python installed by running
python -V. The latest version of Python v2.7 is recommended, which is
2.7.11 as of this writing. Python v2.6.x and v3 do not work. On Windows, we
recommend the use of native Python v2.7, not Cygwin Python. If you don’t have
one of these versions of Python installed, download and install the latest
version of Python v2.7. Make sure that the path to the installation directory
has no spaces in it (e.g. on Windows, do not install Python in the “Program
Files” directory):
% python --version
Python 2.7.11

pip¶
Many Python installations already include pip, but in case yours does
not, get it with the pip install instructions:
% pip --version
pip 10.0.1 from ... (python 2.7)

virtualenv¶
If you do not have an OS-provided copy of virtualenv, install it with the
instructions from the virtualenv documentation:
% virtualenv --version
15.1.0

C compiler and libraries¶
Except on OS-X, where the Tahoe project hosts pre-compiled wheels for all
dependencies, you will need several C libraries installed before you can
build. You will also need the Python development headers, and a C compiler
(your python installation should know how to find these).
On Debian/Ubuntu-derived systems, the necessary packages are python-dev,
libffi-dev, and libssl-dev, and can be installed with apt-get. On
RPM-based system (like Fedora) these may be named python-devel, etc,
instead, and cam be installed with yum or rpm.
Note that Tahoe-LAFS depends on openssl 1.1.1c or greater.

Install the Latest Tahoe-LAFS Release¶
We recommend creating a fresh virtualenv for your Tahoe-LAFS install, to
isolate it from any python packages that are already installed (and to
isolate the rest of your system from Tahoe’s dependencies).
This example uses a virtualenv named venv, but you can call it anything
you like. Many people prefer to keep all their virtualenvs in one place, like
~/.local/venvs/ or ~/venvs/.
It’s usually a good idea to upgrade the virtualenv’s pip and
setuptools to their latest versions, with venv/bin/pip install -U pip
setuptools. Many operating systems have an older version of virtualenv,
which then includes older versions of pip and setuptools. Upgrading is easy,
and only affects the virtualenv: not the rest of your computer.
Then use the virtualenv’s pip to install the latest Tahoe-LAFS release
from PyPI with venv/bin/pip install tahoe-lafs. After installation, run
venv/bin/tahoe --version to confirm the install was successful:
% virtualenv venv
New python executable in ~/venv/bin/python2.7
Installing setuptools, pip, wheel...done.

% venv/bin/pip install -U pip setuptools
Downloading/unpacking pip from https://pypi.python.org/...
...
Successfully installed pip setuptools

% venv/bin/pip install tahoe-lafs
Collecting tahoe-lafs
...
Installing collected packages: ...
Successfully installed ...

% venv/bin/tahoe --version
tahoe-lafs: 1.14.0
foolscap: ...

%

Install From a Source Tarball¶
You can also install directly from the source tarball URL. To verify
signatures, first see verifying_signatures and replace the URL in the
following instructions with the local filename.

% virtualenv venv
New python executable in ~/venv/bin/python2.7
Installing setuptools, pip, wheel…done.
% venv/bin/pip install https://tahoe-lafs.org/downloads/tahoe-lafs-1.14.0.tar.bz2
Collecting https://tahoe-lafs.org/downloads/tahoe-lafs-1.14.0.tar.bz2
…
Installing collected packages: …
Successfully installed …
% venv/bin/tahoe –version
tahoe-lafs: 1.14.0
…

Verifying Signatures¶
First download the source tarball and then any signatures. There are several
developers who are able to produce signatures for a release. A release may
have multiple signatures. All should be valid and you should confirm at least
one of them (ideally, confirm all).
This statement, signed by the existing Tahoe release-signing key, attests to
those developers authorized to sign a Tahoe release:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

January 20, 2021

Any of the following core Tahoe contributers may sign a release. Each
release MUST be signed by at least one developer but MAY have
additional signatures. Each developer independently produces a
signature which is made available beside Tahoe releases after 1.15.0

This statement is signed by the existing Tahoe release key. Any future
such statements may be signed by it OR by any two developers (for
example, to add or remove developers from the list).

meejah
0xC2602803128069A7
9D5A 2BD5 688E CB88 9DEB CD3F C260 2803 1280 69A7
https://meejah.ca/meejah.asc

jean-paul calderone (exarkun)
0xE27B085EDEAA4B1B
96B9 C5DA B2EA 9EB6 7941 9DB7 E27B 085E DEAA 4B1B
https://twistedmatrix.com/~exarkun/E27B085EDEAA4B1B.asc

brian warner (lothar)
0x863333C265497810
5810 F125 7F8C F753 7753  895A 8633 33C2 6549 7810
https://www.lothar.com/warner-gpg.html

-----BEGIN PGP SIGNATURE-----

iQEzBAEBCgAdFiEE405i0G0Oac/KQXn/veDTHWhmanoFAmAHIyIACgkQveDTHWhm
anqhqQf/YSbMXL+gwFhAZsjX39EVlbr/Ik7WPPkJW7v1oHybTnwFpFIc52COU1x/
sqRfk4OyYtz9IBgOPXoWgXu9R4qdK6vYKxEsekcGT9C5l0OyDz8YWXEWgbGK5mvI
aEub9WucD8r2uOQnnW6DtznFuEpvOjtf/+2BU767+bvLsbViW88ocbuLfCqLdOgD
WZT9j3M+Y2Dc56DAJzP/4fkrUSVIofZStYp5u9HBjburgcYIp0g/cyc4xXRoi6Mp
lFTRFv3MIjmoamzSQseoIgP6fi8QRqPrffPrsyqAp+06mJnPhxxFqxtO/ZErmpSa
+BGrLBxdWa8IF9U1A4Fs5nuAzAKMEg==
=E9J+
-----END PGP SIGNATURE-----

Signatures are made available beside the release. So for example, a release
like https://tahoe-lafs.org/downloads/tahoe-lafs-1.16.0.tar.bz2 might
have signatures tahoe-lafs-1.16.0.tar.bz2.meejah.asc and
tahoe-lafs-1.16.0.tar.bz2.warner.asc.
To verify the signatures using GnuPG:
% gpg --verify tahoe-lafs-1.16.0.tar.bz2.meejah.asc tahoe-lafs-1.16.0.tar.bz2
gpg: Signature made XXX
gpg:                using RSA key 9D5A2BD5688ECB889DEBCD3FC2602803128069A7
gpg: Good signature from "meejah <meejah@meejah.ca>" [full]
% gpg --verify tahoe-lafs-1.16.0.tar.bz2.warner.asc tahoe-lafs-1.16.0.tar.bz2
gpg: Signature made XXX
gpg:                using RSA key 967EFE06699872411A77DF36D43B4C9C73225AAF
gpg: Good signature from "Brian Warner <warner@lothar.com>" [full]

Extras¶
Tahoe-LAFS provides some functionality only when explicitly requested at installation time.
It does this using the “extras” feature of setuptools.
You can request these extra features when running the pip install command like this:
% venv/bin/pip install tahoe-lafs[tor]

This example enables support for listening and connecting using Tor.
The Tahoe-LAFS documentation for specific features which require an explicit install-time step will mention the “extra” that must be requested.

Hacking On Tahoe-LAFS¶
To modify the Tahoe source code, you should get a git checkout, and install
with the --editable flag. You should also use the [test] extra to get
the additional libraries needed to run the unit tests:
% git clone https://github.com/tahoe-lafs/tahoe-lafs.git

% cd tahoe-lafs

% virtualenv venv

% venv/bin/pip install --editable .[test]
Obtaining file::~/tahoe-lafs
...
Successfully installed ...

% venv/bin/tahoe --version
tahoe-lafs: 1.14.0.post34.dev0
...

This way, you won’t have to re-run the pip install step each time you
modify the source code.

Running the tahoe executable¶
The rest of the Tahoe-LAFS documentation assumes that you can run the
tahoe executable that you just created. You have four basic options:

Use the full path each time (e.g. ~/venv/bin/tahoe).
“Activate” the virtualenv with . venv/bin/activate, to get a
subshell with a $PATH that includes the venv/bin/ directory, then
you can just run tahoe.
Change your $PATH to include the venv/bin/ directory, so you can
just run tahoe.
Symlink from ~/bin/tahoe to the tahoe executable. Since ~/bin
is typically in your $PATH (at least if it exists when you log in),
this will let you just run tahoe.

You might also find the pipsi tool convenient: pipsi install
tahoe-lafs will create a new virtualenv, install tahoe into it, then
symlink just the executable (into ~/.local/bin/tahoe). Then either add
~/.local/bin/ to your $PATH, or make one last symlink into
~/bin/tahoe.

Running the Self-Tests¶
To run the self-tests from a source tree, you’ll need tox installed. On a
Debian/Ubuntu system, use apt-get install tox. You can also install it
into your tahoe-specific virtualenv with pip install tox.
Then just run tox. This will create a new fresh virtualenv, install Tahoe
(from the source tree, including any changes you have made) and all its
dependencies (including testing-only dependencies) into the virtualenv, then
run the unit tests. This ensures that the tests are repeatable and match the
results of other users, unaffected by any other Python packages installed on
your machine. On a modern computer this will take 5-10 minutes, and should
result in a “all tests passed” mesage:
% tox
GLOB sdist-make: ~/tahoe-lafs/setup.py
py27 recreate: ~/tahoe-lafs/.tox/py27
py27 inst: ~/tahoe-lafs/.tox/dist/tahoe-lafs-1.14.0.post8.dev0.zip
py27 runtests: commands[0] | tahoe --version
py27 runtests: commands[1] | trial --rterrors allmydata
allmydata.test.test_auth
  AccountFileCheckerKeyTests
    test_authenticated ...                                           [OK]
    test_missing_signature ...                                       [OK]
 ...
Ran 1186 tests in 423.179s

PASSED (skips=7, expectedFailures=3, successes=1176)
__________________________ summary ___________________________________
  py27: commands succeeded
  congratulations :)

Common Problems¶
If you see an error like fatal error: Python.h: No such file or directory
while compiling the dependencies, you need the Python development headers. If
you are on a Debian or Ubuntu system, you can install them with sudo
apt-get install python-dev. On RedHat/Fedora, install python-devel.
Similar errors about openssl/crypto.h indicate that you are missing the
OpenSSL development headers (libssl-dev). Likewise ffi.h means you
need libffi-dev.
Note that Tahoe-LAFS depends on openssl 1.1.1c or greater.

Using Tahoe-LAFS¶
Now you are ready to deploy a decentralized filesystem. You will use the
tahoe executable to create, configure, and launch your Tahoe-LAFS nodes.
See How To Run Tahoe-LAFS for instructions on how to do that.