1 Welcome to the Allmydata-Tahoe project. This project implements a secure,
2 distributed, fault-tolerant storage grid. All of the source code is available
3 under a Free Software licence.
5 The basic idea is that the data in this storage grid is spread over all
6 participating nodes, using an algorithm that can recover the data even if
7 some of the nodes are not available.
9 The interface to the storage grid allows you to store and fetch files, either
10 by self-authenticating cryptographic identifier or by filename and path.
12 See the web site for all kinds of information, news, and community
18 GETTING PRECOMPILED BINARIES FOR DEBIAN-LIKE SYSTEMS:
20 Pre-compiled binaries are available for Debian or Ubuntu. Please see the
21 following web page for instructions:
23 http://allmydata.org/trac/tahoe/wiki/DownloadDebianPackages
28 If you are building on Windows, then the easy way is to install cygwin and
29 use cygwin version of Python and the cygwin versions of all dependencies
30 (which will happen naturally if you follow this README -- note that you
31 cannot use Windows-native versions of any of the dependencies -- they all
32 have to be cygwin versions).
34 The second-easiest way is to install cygwin and use cygwin development tools
35 such as bash, GNU make, gcc, etc., but install the Windows-native version of
36 Python and the Windows-native versions of all of the dependencies. If you
37 create a distutils config file (as per
38 http://docs.python.org/inst/config-syntax.html ) and put "compiler=mingw32"
39 in it, then you can follow the rest of this README and the dependencies will
40 all be automatically built (by the cygwin gcc compiler) as Windows-native
43 The third-easiest way is to use a Microsoft compiler or some other compiler.
44 This README does not explain how to do that. You are on your own for now,
45 but please feel free to contribute a document which explains how to build all
46 these dependencies using your favorite compiler.
51 If you aren't getting a pre-compiled binary, then you'll have to ensure that
52 the following packages are installed before you install Tahoe.
54 There are two kinds of dependencies, "manual dependencies" and
55 "easy_install-able dependencies". The latter kind are normally automatically
56 satisfied for you when you install Tahoe, but if something goes wrong, please
57 see the EASY_INSTALLABLE DEPENDENCIES section below.
59 All of the manual dependencies can probably be installed through your
60 standard package management tool if you are running on a modern Unix
61 operating system. For example, on an debian-like system, you can do "sudo
62 apt-get install gcc make python-dev python-twisted python-pyopenssl".
64 The Manual Dependencies:
66 + a C compiler (language)
68 + GNU make (build tool)
70 + Python 2.4 or newer (tested against 2.4, and 2.5.1 ), including
71 development headers (language)
75 + Twisted Python (tested against 2.2.0, 2.4.0, and 2.5.0) (network and
76 operating system integration library)
78 http://twistedmatrix.com/
80 You need the following subpackages, which are included in the default
83 * core (the standard Twisted package)
86 Twisted requires zope.interface, a copy of which is included in the
87 Twisted distribution. Note that Twisted does *not* require the entire Zope
88 distribution, merely the much smaller zope.interface component.
90 + Python PyOpenSSL (0.6 or later) (secure transport layer)
92 http://pyopenssl.sourceforge.net
94 To install PyOpenSSL on Windows-native, download this:
95 http://allmydata.org/source/pyOpenSSL-0.6.win32-py2.5.exe
97 or for Python 2.4, this:
99 http://allmydata.org/source/pyOpenSSL-0.6.win32-py2.4.exe
101 To install PyOpenSSL on Windows-cygwin, install the OpenSSL development
102 libraries with the cygwin package management tool, then get the pyOpenSSL
103 source code, cd into it, and run "python ./setup.py install".
105 + OpenSSL, including development headers (cryptography library); not
106 required on native Windows (required on cygwin)
110 The Windows-native pyOpenSSL package comes with OpenSSL, which is why you
111 don't need to install OpenSSL separately on Windows-native.
113 + the pywin32 package (210 or later); required only on native Windows (not
116 http://sourceforge.net/projects/pywin32/
119 GETTING THE SOURCE CODE:
121 You need the source code if you are going to install The Debian Way, The
122 Setuptools Way, or The Running-In-Place Way (see below). You do not need the
123 source code if you are getting precompiled binaries for Debian or Ubuntu (see
124 above), or if you are going to install The easy_install Way (see below).
126 The code is available via darcs by running the following command:
128 darcs get http://allmydata.org/source/tahoe/trunk tahoe
130 This will create a directory named "tahoe" in the current working directory
131 and put a copy of the latest source code into it. Later, if you want to get
132 any new changes, then cd into that directory and run the command "darcs
135 Tarballs of sources are available at:
137 http://allmydata.org/source/tahoe/
142 There are four ways to do it: The easy_install Way, The Setuptools Way, The
143 Running-In-Place Way, and The Debian Way. Choose one:
145 The easy_install Way:
147 You don't need to download the source code first.
149 Tahoe is registered with the Python Package Index (PyPI), so the
150 'easy_install' tool can download and install it for you. Just type
151 'easy_install allmydata-tahoe' from any shell. That will download the most
152 recent Tahoe source tarball, unpack it in a temporary directory, install it
153 to the standard location, then download and install any easy_install-able
154 dependencies that you need (setuptools, zfec, foolscap, simplejson, and
155 nevow). (This will work only if you already have the dependencies listed
156 in the MANUAL DEPENDENCIES section, above.)
160 Get the source code (see above).
162 Run 'python setup.py install'. This will compile and install the Tahoe code
163 to the standard location for your operating system (on unix, that is
164 somewhere inside /usr/lib/). It will also acquire and install the
165 easy_install-able dependencies (setuptools, zfec, foolscap, simplejson, and
166 nevow) to the same place.
168 (To install it to a non-standard location, see
169 http://allmydata.org/trac/tahoe/wiki/SetuptoolsAndGNUStow .)
171 The Running-In-Place Way:
173 You can use Tahoe without installing it. The steps are these:
175 1. Get the source code (see above).
177 2. Run "make build-deps" to install the easy_install-able dependencies
178 (setuptools, zfec, foolscap, simplejson, and nevow) into a local
179 subdirectory of the Tahoe source distribution.
181 3. Build Tahoe by running "make".
183 4. Once you've built it then you can execute "./bin/allmydata-tahoe". (When
184 the allmydata-tahoe script is in a Tahoe source distribution, it adds
185 the necessary directory to the Python "sys.path". It also looks for any
186 dependencies that you installed by "make build-deps" and includes them
187 in the sys.path.) See the RUNNING section, below.
191 The Debian Way is to build .deb files which you can then install with
194 This requires certain debian packages (build-essential, fakeroot,
195 devscripts, debhelper, cdbs) to be installed first, since they are used to
196 construct the Tahoe .deb files. A full list of these required packages can
197 be found in the "Build-Depends" line in the misc/DIST/debian/control in the
198 top-level tahoe directory (replacing the word DIST with etch, dapper, edgy,
199 or feisty as appropriate).
201 Get the source code (see above).
203 If you're running on a debian system, run 'make deb-etch', 'make deb-sid',
204 'make deb-edgy', or 'make deb-feisty' from within the tahoe top-level
205 directory to construct a debian package named 'allmydata-tahoe' which you
206 can then install with dpkg.
209 TESTING THAT IT IS PROPERLY INSTALLED
211 'make check-deps' checks that all of the required Python package
212 dependencies are installed.
214 'make test' runs the unit test suites. (This can take a long time on
215 slow computers. There are a lot of tests and some of them do a lot of
216 public-key cryptography.)
218 Executing the allmydata-tahoe script from the "bin" subdirectory will work
219 only if Tahoe itself is installed, either because it is installed into the
220 local subdirectory (as per "The Running-In-Place Way") or because it is
221 installed into your system (as per the other three ways of installing).
226 Run the "allmydata-tahoe" executable.
228 If you installed "The Running-In-Place Way", then it is in your source tree,
229 in the "bin" subdirectory thereof. If you installed in one of the other
230 three ways, then it has been installed into your operating system's
231 filesystem, perhaps in "/usr/bin" on Unix, or in "C:\Python25\Scripts" on
234 The "allmydata-tahoe" utility is used to create, start, and stop nodes.
235 Each node lives in a separate base directory, inside of which you can add
236 files to configure and control the node. Nodes also read and write files
237 within that directory.
239 A grid consists of a single central 'introducer and vdrive' node and one or
240 more 'client' nodes. If you are joining an existing grid, the
241 introducer-and-vdrive node will already be running, and you'll just need to
242 create a client node. If you're creating a brand new grid, you'll need to
243 create both an introducer-and-vdrive and a client (and then invite other
244 people to create their own client nodes and join your grid).
246 The introducer (-and-vdrive) node is constructed by running 'allmydata-tahoe
247 create-introducer --basedir $HERE'. Once constructed, you can start the
248 introducer by running 'allmydata-tahoe start --basedir $HERE' (or, if you
249 are already in the introducer's base directory, just type 'allmydata-tahoe
250 start'). Inside that base directory, there will be a pair of files
251 'introducer.furl' and 'vdrive.furl'. Make a copy of these, as they'll be
252 needed on the client nodes.
254 To construct a client node, pick a new working directory for it, then run
255 'allmydata-tahoe create-client --basedir $HERE'. Copy the two .furl files
256 from the introducer into this new directory, then run 'allmydata-tahoe start
257 --basedir $HERE'. After that, the client node should be off and running.
258 The first thing it will do is connect to the introducer and introduce itself
259 to all other nodes on the grid. You can follow its progress by looking at
260 the $HERE/logs/twistd.log file.
262 To actually use the client, enable the web interface by writing a port
263 number (like "8123") into a file named $HERE/webport and then restarting the
264 node with 'allmydata-tahoe restart --basedir $HERE'. This will prompt the
265 client node to run a webserver on the desired port, through which you can
266 view, upload, download, and delete files. This 'webport' file is actually a
267 "strports specification", defined in
268 http://twistedmatrix.com/documents/current/api/twisted.application.strports.html
269 , so you can have it only listen on a local interface by writing
270 "tcp:8123:interface=127.0.0.1" to this file, or make it use SSL by writing
271 "ssl:8123:privateKey=mykey.pem:certKey=cert.pem" instead.
273 A client node directory can also be created without installing the code
274 first. Just use 'make create-client', and a new directory named 'CLIENTDIR'
275 will be created inside the top of the source tree. Copy the relevant .furl
276 files in, set the webport, then start the node by using 'make start-client'.
277 To stop it again, use 'make stop-client'. Similar makefile targets exist
278 for making and running an introducer node.
280 If you are behind a firewall and you can configure your firewall to forward
281 TCP connections on a port to the computer running your Tahoe node, then you
282 can configure the Tahoe node to announce itself as being available on that
283 IP address and port. The way to do this is to create a file named
284 $HERE/advertised_ip_addresses, in which you can put IP addresses and port
285 numbers in "dotted-quad:port" form, e.g. "209.97.232.113:1345". You can put
286 multiple IP-address-and-port-number entries into this file, on separate
289 There is a public grid available for testing. See
290 http://allmydata.org/trac/tahoe/wiki/TestGrid for the necessary .furl files.
295 This program is free software; you can redistribute it and/or modify it
296 under the terms of the GNU General Public License as published by the Free
297 Software Foundation; either version 2 of the License, or (at your option)
298 any later version, with the added permission that, if you become obligated
299 to release a derived work under this licence (as per section 2.b), you may
300 delay the fulfillment of this obligation for up to 12 months. If you are
301 obligated to release code under section 2.b of this licence, you are
302 obligated to release it under these same terms, including the 12-month grace
303 period clause. See the COPYING file for details.
306 EASY_INSTALLABLE DEPENDENCIES
308 The following Python packages are required, but normally they are
309 automatically installed as a side-effect of installing Tahoe.
311 + Python setuptools (build and distribution tool)
313 http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
315 The Tahoe install process will automatically download and install
316 setuptools if it is not present. However, if an old, incompatible version
317 of setuptools is present (< v0.6c6 on Cygwin, or < v0.6a9 on other
318 platforms), then the install will fail.
320 If the install fails due to your current version of setuptools being
321 incompatible, please either upgrade or uninstall your version of
322 setuptools and re-run the install.
324 + zfec (erasure coding library)
326 http://cheeseshop.python.org/pypi/zfec
328 zfec is packaged in a setuptools-compatible way and included in the Python
329 Package Index (PyPI), so it will be automatically installed when you
330 install Tahoe (see INSTALLING). It can be manually installed by running
333 + Python foolscap (secure remote object library)
335 http://cheeseshop.python.org/pypi/foolscap
337 foolscape is packaged in a setuptools-compatible way and included in the
338 Python Package Index (PyPI), so it will be automatically installed when
339 you install Tahoe (see INSTALLING). It can be manually installed by
340 running "easy_install foolscap".
342 + Python simplejson (JSON parser)
344 http://cheeseshop.python.org/pypi/simplejson
346 simplejson is packaged in a setuptools-compatible way and included in the
347 Python Package Index (PyPI), so it will be automatically installed when
348 you install Tahoe (see INSTALLING). It can be manually installed by
349 running "easy_install simplejson".
351 + Python Nevow (0.6.0 or later) (web presentation language)
353 http://divmod.org/trac/wiki/DivmodNevow
355 Note that the current version of Nevow (0.9.18) requires Twisted 2.4.0 or
358 Nevow is packaged in a setuptools-compatible way and included in the
359 Python Package Index (PyPI), so it will be automatically installed when
360 you install Tahoe (see INSTALLING). It can be manually installed by
361 running "easy_install nevow".